From 8333294d0e8b569a65518b29237249dce5818e23 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adolfo=20Garc=C3=ADa=20Veytia=20=28Puerco=29?=
 <puerco@chainguard.dev>
Date: Mon, 16 Jan 2023 15:07:14 -0600
Subject: [PATCH] Add JSON-LD changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Corrected the examples to reflect the current json ld schema idea
and added  a section about the public shared namespace to the specification.

Signed-off-by: Adolfo García Veytia (Puerco) <puerco@chainguard.dev>
---
 OPENVEX-SPEC.md | 73 ++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 63 insertions(+), 10 deletions(-)

diff --git a/OPENVEX-SPEC.md b/OPENVEX-SPEC.md
index d9ff3c2..5997397 100644
--- a/OPENVEX-SPEC.md
+++ b/OPENVEX-SPEC.md
@@ -137,8 +137,8 @@ Here is a sample of a minimal OpenVEX document:
 
 ```json
 {
-  "@context": "https://openvex.dev/schema-ld.json",
-  "@id": "VEX-9fb3463de1b57",
+  "@context": "https://openvex.dev/ns",
+  "@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57",
   "author": "Wolfi J Inkinson",
   "role": "Document Creator",
   "timestamp": "2023-01-08T18:02:03.647787998-06:00",
@@ -163,7 +163,8 @@ The following table lists the fields in the document struct
 
 | Field | Required | Description |
 | --- | --- | --- |
-| @id | ✓ | id is the identifying string for the VEX document. This should be unique per document. |
+| @context | ✓ | The URL linking to the OpenVEX context definition. Fixed to `https://openvex.dev/ns`. | 
+| @id | ✓ | The IRI identifying the VEX document.  |
 | author | ✓ | Author is the identifier for the author of the VEX statement. Ideally, a common name, may be a URI. `author` can be an individual or organization. The author identity SHOULD be cryptographically associated with the signature of the VEX  statement or document or transport. |
 | role | ✓ | role describes the role of the document author.  | 
 | timestamp | ✓ | Timestamp defines the time at which the document was issued. | 
@@ -337,9 +338,9 @@ example, the sole statement has its timestamp data derived from the document:
 
 ```json
 {
-  "@context": "https://openvex.dev/schema-ld.json",
-  "@id": "VEX-9fb3463de1b57",
-  "author": "Unknown Author",
+  "@context": "https://openvex.dev/ns",
+  "@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57",
+  "author": "Wolfi J Inkinson",
   "role": "Document Creator",
   "timestamp": "2023-01-08T18:02:03-06:00",
   "version": "1",
@@ -362,9 +363,9 @@ to avoid duplication:
 
 ```json
 {
-  "@context": "https://openvex.dev/schema-ld.json",
-  "@id": "VEX-6ea13336fa2ffb7",
-  "author": "Unknown Author",
+  "@context": "https://openvex.dev/ns",
+  "@id": "https://openvex.dev/docs/example/vex-84822c4e5028c",
+  "author": "Wolfi J Inkinson",
   "role": "Document Creator",
   "timestamp": "2023-01-09T09:08:42-06:00",
   "version": "1",
@@ -388,12 +389,64 @@ to avoid duplication:
 }
 ```
 
+## OpenVEX and JSON-LD
+
+OpenVEX documents express data that is by nature interlinked. Documents and are
+designed to be understood by [JSON-LD](https://www.w3.org/TR/json-ld11/) parsers,
+this lets them reference resources expressed in other json-ld formats such as
+[SPDX 3](https://github.com/spdx/spdx-3-model). 
+
+### VEX Extensions
+
+To make VEX documents JSON-LD compatible, OpenVEX extends the VEX minimum
+requirements in the the following two ways:
+
+1. OpenVEX extends the document identifier required by VEX to make the strings
+compatible with the Internationalized Resource Identifier (IRI) specification
+(see [RFC3987](https://www.rfc-editor.org/rfc/rfc3987)). 
+
+2. Addition of the `@context` field at the document level. The additional field is
+not required by VEX but it is added to make the documents parseable by json-ld
+processors. 
+
+### Public IRI Namespaces
+
+As all documents are required to be identified by an IRI, open vex defines a 
+public namespace that can be used by documents. Users of OpenVEX MAY choose to
+use the shared namespace.
+
+The shared namespace is defined under the openvex.dev domain name:
+
+`    https://openvex.dev/docs/[name]    `
+
+Users can start issuing IRIs for their documents by appending a IRI valid string
+to the shared namespace:
+
+`    https://openvex.dev/docs/[myproject]    `
+
+There are two reserved shared namespaces with special meanings:
+
+- `public` this is a public shared name where anybody that needs a valid IRI can
+issue identifiers. Only recommended for demos or experiments where name collisions
+don't matter.
+- `example` a namespace for documentation, demos or other uses where no systems
+are expected to run.
+
+Please note that initially, OpenVEX does not provide a registry of namespaces or
+hosting or redirection of IRIs. 
+
+For more information check the OpenVEX [JSON-LD](JSON-LD.md) document and the
+W3C's [JSON-LD reommendation](https://www.w3.org/TR/json-ld11/).
+
+
+
 ## Revisions 
 
 | Date | Revision |
 | --- | --- | 
 | 2023-01-08 | First Draft of the OpenVEX Specification |
-| 2023-01-16 | Updated to reflect @luhring's review |
+| 2023-01-16 | Updated specx draft to reflect initial review |
+| 2023-01-16 | Added JSON-LD and namespace section |
 
 
 ## Sources