From 544cb1a57303f80d228cedf5eebfd77abd93d438 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Thu, 28 Dec 2023 13:14:20 -0500 Subject: [PATCH 1/9] Add vocabulary README.md. --- vocab/README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 vocab/README.md diff --git a/vocab/README.md b/vocab/README.md new file mode 100644 index 0000000..f71d38c --- /dev/null +++ b/vocab/README.md @@ -0,0 +1,11 @@ +# Generate RDFS vocabulary files + +The script in the directory generates RDFS vocabulary files in JSON and Turtle formats, plus a human readable HTML file containing the vocabulary in RDFa, based on a simple vocabulary definition in a YAML file. This is done using the [yml2vocab](https://github.com/w3c/yml2vocab); more details about the script can also be found in the [yml2vocab readme file](https://github.com/w3c/yml2vocab). + +The generation of the final files is done via a github action (see `/.github/workflows/generate-vocab-files.yml`). + +## Content of the directory + +- `README.md`: this file. +- `index.yml`: the core vocabulary specification. _Any change on the vocabulary must be made by modifying this file;_ see the separate [description](https://github.com/w3c/yml2vocab) of the underlying YAML format. +- `template.html`: an HTML template file used by the script; it is the skeleton of the final HTML format based on [ReSpec](https://respec.org/docs/). If the file is modified, care should be taken not to change the core structure and the various, possibly empty, HTML elements with `@id` values. The script fills those elements with content when generating the `index.html` file (and removes any sections that remain empty after processing). From 29d83f8d71db3ffc5c838b3af7b1714caa18542f Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Thu, 28 Dec 2023 13:14:34 -0500 Subject: [PATCH 2/9] Add template for vocabulary documentation. --- vocab/template.html | 226 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 vocab/template.html diff --git a/vocab/template.html b/vocab/template.html new file mode 100644 index 0000000..9d71e9d --- /dev/null +++ b/vocab/template.html @@ -0,0 +1,226 @@ + + + + + + + + + + +
+

This document describes the , i.e., + the . +

+

Alternate versions of the vocabulary definition exist in + Turtle and + JSON-LD. +

+
+
Published:
+
Version Info:
+
1.0
+
See Also:
+
+
+
+

+This vocabulary has been defined by the + +W3C Verifiable Credentials Working Group and provides the official RDFS +vocabulary for + +Bitstring Status Lists. Comments regarding this document are welcome. +Please file issues directly on +GitHub, or +send them to +public-vc-comments@w3.org +( +subscribe, + +archives). +

+
+
+

Specification of terms

+

+In general, the terms — i.e., the properties and classes — used in +the VCDM are formally specified in Recommendation Track documents published by +the W3C Verifiable Credentials Working +Group or, for some deprecated or reserved terms, in Reports published by the +W3C Credentials Community +Group. In each case of such external definition, the term's description in +this document contains a link to the relevant specification. Additionally, the +`rdfs:definedBy` property in the RDFS representation(s) refers to the formal +specification. +

+

+In some cases, a local explanation is necessary to complement, or to replace, +the definition found in an external specification. For instance, this is so when +the term is needed to provide a consistent structure to the RDFS vocabulary, +such as when the term defines a common supertype for class instances that are +used as objects of specific properties, or when +RDF Graphs +are involved. For such cases, the extra definition is included in the current +document (and the `rdfs:comment` property is used to include them in the RDFS +representations). +

+
+
+

Namespaces

+

This specification makes use of the following namespaces:

+
+
+
+ +
+

Regular terms

+ +
+

Class definitions

+
+ +
+

Property definitions

+
+ +
+

Datatype definitions

+
+ +
+

Definitions for individuals

+
+
+ +
+

Deprecated terms

+ +

+All terms in this section are deprecated, and are only +kept in this vocabulary for backward compatibility. +

+

+New applications should not use them. +

+ +
+

Deprecated classes

+
+ +
+

Deprecated properties

+
+ +
+

Deprecated properties

+
+ +
+

Deprecated individuals

+
+
+ + + From 3cb5818d1028941068fd14543316221c401bf5d6 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Thu, 28 Dec 2023 13:14:47 -0500 Subject: [PATCH 3/9] Add vocabulary definition file. --- vocab/index.yml | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 vocab/index.yml diff --git a/vocab/index.yml b/vocab/index.yml new file mode 100644 index 0000000..9266cf8 --- /dev/null +++ b/vocab/index.yml @@ -0,0 +1,91 @@ +vocab: + - id: sl + value: https://www.w3.org/ns/credentials/status-list# + +prefix: + - id: cred + value: https://w3.org/2018/credentials# + +ontology: + - property: dc:title + value: Verifiable Credentials Bitstring Status List v1.0 + + - property: dc:description + value: RDFS [[RDF-SCHEMA]] vocabulary used by the Verifiable Credentials Bitstring Status List [[VC-BITSTRING-STATUS-LIST]] + + - property: rdfs:seeAlso + value: https://www.w3.org/TR/vc-bitstring-status-list/ + +class: + - id: BitstringStatusList + label: Bitstring status list + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#bitstringstatuslist + + - id: BitstringStatusListEntry + label: Bitstring status list entry + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#bitstringstatuslistentry + + - id: BitstringStatusListCredential + label: Bitstring status list credential + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#bitstringstatuslistcredential + +property: + - id: statusPurpose + label: Status purpose + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#statusPurpose + domain: + - sl:BitstringStatusList + - sl:BitstringStatusListEntry + range: xsd:string + + - id: statusListIndex + label: Status list index + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#statusListIndex + domain: sl:BitstringStatusListEntry + range: xsd:string + + - id: statusListCredential + label: Status list credential + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#statusListCredential + domain: sl:BitstringStatusListEntry + range: xsd:string + + - id: encodedList + label: Encoded list + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#encodedList + domain: sl:BitstringStatusList + range: xsd:base64Binary + + - id: ttl + label: Time to live in milliseconds + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#ttl + domain: sl:BitstringStatusList + range: xsd:string + + - id: size + label: Bitstring entry size in bits + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#size + domain: sl:BitstringStatusList + range: xsd:string + + - id: statusMessage + label: Status messages + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#statusMessage + domain: sl:BitstringStatusList + range: xsd:string + + - id: value + label: Hexadecimal value of a message + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#value + range: xsd:string + + - id: message + label: Human-readable message of a status value + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#message + range: xsd:string + + - id: reference + label: Reference documentation for status messages + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#reference + domain: sl:BitstringStatusList + range: xsd:string From b0bfc4395d53124714eb0f207495fa3e101492c8 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Thu, 28 Dec 2023 13:15:03 -0500 Subject: [PATCH 4/9] Add Github pages build commands for vocabulary files. --- .github/workflows/gh-pages.yml | 47 ++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 .github/workflows/gh-pages.yml diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..5088907 --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,47 @@ +name: Publish to Github Pages +on: + push: + branches: [main] + # Allows workflow to be triggered manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout/@v3 + - name: Setup Node 18 + uses: actions/setup-node@v3 + with: + node-version: 18 + - name: Generate vocabulary + run: | + npm install yml2vocab + npm update yml2vocab + ./node_modules/.bin/yml2vocab -v vocab/vocabulary.yml -t vocab/template.html + rm -rf node_modules + - name: Setup Github Pages + uses: actions/configure-pages@v2 + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + # Upload entire repository + path: '.' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 From becd62c53e050f7a6ffa62455c84fddd0525bd9f Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Thu, 28 Dec 2023 13:24:35 -0500 Subject: [PATCH 5/9] Add and fix anchors from vocabulary document to specification. --- index.html | 44 +++++++++++++++++++++----------------------- vocab/index.yml | 6 +++--- 2 files changed, 24 insertions(+), 26 deletions(-) diff --git a/index.html b/index.html index ad7c736..2b90e48 100644 --- a/index.html +++ b/index.html @@ -440,7 +440,7 @@

BitstringStatusListEntry

BitstringStatusListCredential

-When a status list verifiable credential is published, it MUST be a +When a status list verifiable credential is published, it MUST be a conforming document, as defined in [[VC-DATA-MODEL-2.0]], that expresses the data model in this section. The following section describes the format of the verifiable credential that encapsulates the status list: @@ -491,13 +491,13 @@

BitstringStatusListCredential

credentialSubject.type - + The `type` of the credential subject, which is the status list, MUST be `BitstringStatusList`. - credentialSubject.statusPurpose + credentialSubject.statusPurpose The purpose of the status entry MUST be a string. While the value of the string is arbitrary, the following values MUST be used for their intended @@ -538,7 +538,7 @@

BitstringStatusListCredential

- credentialSubject.encodedList + credentialSubject.encodedList The `encodedList` property of the credential subject MUST be the GZIP-compressed [[RFC1952]], base-64 encoded [[RFC4648]] bitstring values @@ -553,7 +553,7 @@

BitstringStatusListCredential

- credentialSubject.ttl + credentialSubject.ttl The `ttl` indicates the "time to live" in milliseconds. This property MAY be present. If not present, implementers MUST use a value of `300000` for this @@ -565,39 +565,37 @@

BitstringStatusListCredential

- credentialSubject.size + credentialSubject.size The `size` indicates the size of the status entry in bits. `size` MAY be provided. If `size` is not present as a property of the `credentialStatus`, then `size` MUST be processed as `1`. `size` MUST be an integer greater than zero. If `size` is provided and is greater than `1`, then the property -`credentialStatus.statusMessages` MUST be present, and the number of status +`credentialStatus.statusMessage` MUST be present, and the number of status messages must equal the number of possible values. + credentialSubject.statusMessage - credentialSubject.statusMessages - - -The `statusMessages` property MUST be an array. If present, +The `statusMessage` property MUST be an array. If present, the length of the array must equal the number of possible status states -indicated by `size`. `statusMessages` MAY be present if -`size` is `1`. `statusMessages` MUST be present if +indicated by `size`. `statusMessage` MAY be present if +`size` is `1`. `statusMessage` MUST be present if `size` is greater than `1`. If not present, the message value associated with the bit value of `0` is "unset" and the bit value of `1` is "set". -If present, elements in the `statusMessages` array MUST contain at +If present, elements in the `statusMessage` array MUST contain at minimum two properties:
    -
  • +
  • `status`, being a string of the hex value of the status
    • -
  • -`value`, being a string containing the associated message +
  • +`message`, being a string containing the associated message
-Implementers MAY add additional values to objects in the `statusMessages` array. +Implementers MAY add additional values to objects in the `statusMessage` array. Implementers MAY use the string value of `undefined` in the value to indicate that a corresponding status is not defined for the associated status value, but that it may be defined in the future. Rules for how to handle various status @@ -607,7 +605,7 @@

BitstringStatusListCredential

- credentialSubject.reference + credentialSubject.reference The `reference` property provides a point for implementers to include a [[URL]] to material related to the status. An implementer MAY include the `reference` @@ -664,10 +662,10 @@

BitstringStatusListCredential

"statusPurpose": "status", "reference": "https://example.org/status-dictionary/", "size": 2, - "statusMessages": [ - {"status":"0x0", "value":"valid"}, - {"status":"0x1", "value":"invalid"}, - {"status":"0x2", "value":"pending_review"}, + "statusMessage": [ + {"status":"0x0", "message":"valid"}, + {"status":"0x1", "message":"invalid"}, + {"status":"0x2", "message":"pending_review"}, ... ], "encodedList": "H4sIAAAAAAAAA-3BMQEAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA" diff --git a/vocab/index.yml b/vocab/index.yml index 9266cf8..7c8aef0 100644 --- a/vocab/index.yml +++ b/vocab/index.yml @@ -74,9 +74,9 @@ property: domain: sl:BitstringStatusList range: xsd:string - - id: value - label: Hexadecimal value of a message - defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#value + - id: status + label: Hexadecimal value of a status message + defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#status range: xsd:string - id: message From 0bcf24130ab5698a0773853951d6713817de3313 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 30 Dec 2023 11:24:07 -0500 Subject: [PATCH 6/9] Rename index.yml back to vocabulary.yml. --- vocab/{index.yml => vocabulary.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename vocab/{index.yml => vocabulary.yml} (100%) diff --git a/vocab/index.yml b/vocab/vocabulary.yml similarity index 100% rename from vocab/index.yml rename to vocab/vocabulary.yml From 25b437cdf5f56bb8451fe660c1bbe934cc9019bc Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Tue, 2 Jan 2024 14:50:51 -0500 Subject: [PATCH 7/9] Fix vocabulary based on feedback from @iherman. Co-authored-by: Ivan Herman --- vocab/README.md | 4 ++-- vocab/template.html | 15 ++------------- vocab/vocabulary.yml | 2 +- 3 files changed, 5 insertions(+), 16 deletions(-) diff --git a/vocab/README.md b/vocab/README.md index f71d38c..09c4199 100644 --- a/vocab/README.md +++ b/vocab/README.md @@ -7,5 +7,5 @@ The generation of the final files is done via a github action (see `/.github/wor ## Content of the directory - `README.md`: this file. -- `index.yml`: the core vocabulary specification. _Any change on the vocabulary must be made by modifying this file;_ see the separate [description](https://github.com/w3c/yml2vocab) of the underlying YAML format. -- `template.html`: an HTML template file used by the script; it is the skeleton of the final HTML format based on [ReSpec](https://respec.org/docs/). If the file is modified, care should be taken not to change the core structure and the various, possibly empty, HTML elements with `@id` values. The script fills those elements with content when generating the `index.html` file (and removes any sections that remain empty after processing). +- `vocabulary.yml`: the core vocabulary specification. _Any change on the vocabulary must be made by modifying this file;_ see the separate [description](https://github.com/w3c/yml2vocab) of the underlying YAML format. +- `template.html`: an HTML template file used by the script; it is the skeleton of the final HTML format based on [ReSpec](https://respec.org/docs/). If the file is modified, care should be taken not to change the core structure and the various, possibly empty, HTML elements with `@id` values. The script fills those elements with content when generating the `vocabulary.html` file (and removes any sections that remain empty after processing). diff --git a/vocab/template.html b/vocab/template.html index 9d71e9d..299a413 100644 --- a/vocab/template.html +++ b/vocab/template.html @@ -96,16 +96,6 @@ text-align: center; } - /* This is a bug in the base css setting at W3C. There is an open PR raised for it in the - relevant github repo; if and when that is merged, this statement may become - superfluous. - See https://github.com/w3c/tr-design/pull/336 - */ - figure svg { - max-width: 100%; - margin: auto; - height: auto; - } @@ -160,9 +150,8 @@

Specification of terms

the definition found in an external specification. For instance, this is so when the term is needed to provide a consistent structure to the RDFS vocabulary, such as when the term defines a common supertype for class instances that are -used as objects of specific properties, or when -RDF Graphs -are involved. For such cases, the extra definition is included in the current +used as objects of specific properties. For such cases, +the extra definition is included in the current document (and the `rdfs:comment` property is used to include them in the RDFS representations).

diff --git a/vocab/vocabulary.yml b/vocab/vocabulary.yml index 7c8aef0..c39a554 100644 --- a/vocab/vocabulary.yml +++ b/vocab/vocabulary.yml @@ -11,7 +11,7 @@ ontology: value: Verifiable Credentials Bitstring Status List v1.0 - property: dc:description - value: RDFS [[RDF-SCHEMA]] vocabulary used by the Verifiable Credentials Bitstring Status List [[VC-BITSTRING-STATUS-LIST]] + value: RDFS [[RDF-SCHEMA]] vocabulary used by the [[[VC-BITSTRING-STATUS-LIST]]] [[VC-BITSTRING-STATUS-LIST]] - property: rdfs:seeAlso value: https://www.w3.org/TR/vc-bitstring-status-list/ From e51465643cf3018e5a40c0da568f668bff0a9c26 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 13 Jan 2024 11:10:21 -0500 Subject: [PATCH 8/9] Update vocabulary prefix to one agreed to by VCWG. --- vocab/vocabulary.yml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/vocab/vocabulary.yml b/vocab/vocabulary.yml index c39a554..353ed7b 100644 --- a/vocab/vocabulary.yml +++ b/vocab/vocabulary.yml @@ -1,6 +1,6 @@ vocab: - - id: sl - value: https://www.w3.org/ns/credentials/status-list# + - id: cs + value: https://www.w3.org/ns/credentials/status# prefix: - id: cred @@ -34,44 +34,44 @@ property: label: Status purpose defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#statusPurpose domain: - - sl:BitstringStatusList - - sl:BitstringStatusListEntry + - cs:BitstringStatusList + - cs:BitstringStatusListEntry range: xsd:string - id: statusListIndex label: Status list index defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#statusListIndex - domain: sl:BitstringStatusListEntry + domain: cs:BitstringStatusListEntry range: xsd:string - id: statusListCredential label: Status list credential defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#statusListCredential - domain: sl:BitstringStatusListEntry + domain: cs:BitstringStatusListEntry range: xsd:string - id: encodedList label: Encoded list defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#encodedList - domain: sl:BitstringStatusList + domain: cs:BitstringStatusList range: xsd:base64Binary - id: ttl label: Time to live in milliseconds defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#ttl - domain: sl:BitstringStatusList + domain: cs:BitstringStatusList range: xsd:string - id: size label: Bitstring entry size in bits defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#size - domain: sl:BitstringStatusList + domain: cs:BitstringStatusList range: xsd:string - id: statusMessage label: Status messages defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#statusMessage - domain: sl:BitstringStatusList + domain: cs:BitstringStatusList range: xsd:string - id: status @@ -87,5 +87,5 @@ property: - id: reference label: Reference documentation for status messages defined_by: https://www.w3.org/TR/vc-bitstring-status-list/#reference - domain: sl:BitstringStatusList + domain: cs:BitstringStatusList range: xsd:string From b54d651bb0cf976a7183630443efeef225efc616 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 13 Jan 2024 11:19:40 -0500 Subject: [PATCH 9/9] Update vocabulary URL in template. --- vocab/template.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/vocab/template.html b/vocab/template.html index 299a413..557af40 100644 --- a/vocab/template.html +++ b/vocab/template.html @@ -14,7 +14,7 @@ const retval = content .replace(' var respecConfig = { specStatus: "base", - shortName: "ns/credentials/status-list", - thisVersion: "https://www.w3.org/ns/credentials/status-list/", + shortName: "ns/credentials/status", + thisVersion: "https://www.w3.org/ns/credentials/status/", doJsonLd: true, editors: [{ name: "Ivan Herman", @@ -150,7 +150,7 @@

Specification of terms

the definition found in an external specification. For instance, this is so when the term is needed to provide a consistent structure to the RDFS vocabulary, such as when the term defines a common supertype for class instances that are -used as objects of specific properties. For such cases, +used as objects of specific properties. For such cases, the extra definition is included in the current document (and the `rdfs:comment` property is used to include them in the RDFS representations).