w3c_spec_normative_statements.json

{
  "vc-data-integrity": {
    "Introduction": {
      "Conformance": [
        "Conforming processors MUST produce errors when non-conforming documents are consumed."
      ]
    },
    "Data Model": {
      "Proofs": [
        "When expressing a data integrity proof on an object, a proof property MUST be used.",
        "$.proof: If present, its value MUST be either a single object, or an unordered set of objects",
        "$.proof.id: An optional identifier for the proof, which MUST be a URL [URL], such as a UUID as a URN",
        "$.proof.type: The specific type of proof MUST be specified as a string that maps to a URL [URL].",
        "$.proof.proofPurpose: The reason the proof was created MUST be specified as a string that maps to a URL [URL].",
        "$.proof.verificationMethod: If included, the value MUST be a string that maps to a [URL].",
        "$.proof.cryptosuite: If the proof type is DataIntegrityProof, cryptosuite MUST be specified; otherwise, cryptosuite MAY be specified.",
        "$.proof.cryptosuite: If specified, its value MUST be a string.",
        "$.proof.created: If included, MUST be specified as an [XMLSCHEMA11-2] dateTimeStamp string.",
        "$.proof.expires: If present, it MUST be an [XMLSCHEMA11-2] dateTimeStamp string.",
        "$.proof.domain: If specified, the associated value MUST be either a string, or an unordered set of strings.",
        "$.proof.proofValue: The value MUST use a header and encoding as described in Section 2.4 Multibase of the Controller Documents 1.0 specification to express the binary data.",
        "$.proof.previousProof: Each value identifies another data integrity proof that MUST verify before the current proof is processed.",
        "$.proof.previousProof: If an unordered list, all referenced proofs in the array MUST verify."
      ],
      "Ressource Integrity": [
        "If present, the digestMultibase value MUST be a single string value, or an list of string values, each of which is a Multibase-encoded Multihash value."
      ],
      "Contexts and Vocabularies": [
        "Implementations that perform JSON-LD processing MUST treat the following JSON-LD context URLs as already resolved, where the resolved document matches the corresponding hash values.",
        "Implementations that perform RDF processing MUST treat the JSON-LD serialization of the vocabulary URL as already dereferenced, where the dereferenced document matches the corresponding hash value."
      ],
      "Validating Contexts": [
        "Applications MUST use the algorithm in Section 4.6 Context Validation, or one that achieves equivalent protections, to validate contexts in a conforming secured document.",
        "Context validation MUST be run after running the applicable algorithm in either Section 4.4 Verify Proof or Section 4.5 Verify Proof Sets and Chains."
      ],
      "Context Injection": [
        "If an @context declaration is not included, extensions (such as the addition of new properties) related to this specification or corresponding cryptosuites MUST NOT be made."
      ],
      "Securing Data Losslessly": [
        "Implementations that use JSON-LD processing, such as RDF Dataset Canonicalization [RDF-CANON], MUST throw an error when data is dropped by a JSON-LD processor.",
        "When deserializing to RDF, implementations MUST ensure that the base URL is set to null."
      ],
      "Cryptographic Suites": [
        "The specification MUST be published as a human-readable document at a URL.",
        "The specification MUST identify a cryptographic suite type and any parameters that can be used with the suite.",
        "The specification MUST detail the transformation algorithms (if any), parameters, and other necessary details, used to modify input data into the data to be protected.",
        "The specification MUST detail the hashing algorithms parameters, and other necessary details used to perform cryptographic hashing to the data to be protected.",
        "The specification MUST detail the proof serialization algorithms, parameters, and other necessary details used to perform cryptographic protection of the data.",
        "The specification MUST detail the proof verification algorithms, parameters, and other necessary details used to perform cryptographic verification of the data.",
        "The specification MUST define a data integrity cryptographic suite instantiation algorithm that accepts a set of options (map options) and returns a cryptosuite instance (struct cryptosuite).",
        "The specification MUST detail any known resource starvation attack that can occur in an algorithm and provide testable mitigations against each attack.",
        "The specification MUST contain a Security Considerations section detailing security considerations specific to the cryptographic suite.",
        "The specification MUST contain a Privacy Considerations section detailing privacy considerations specific to the cryptographic suite.",
        "The JSON-LD context associated with the cryptographic suite MUST have its terms protected from unsafe redefinition, by use of the @protected keyword."
      ],
      "Data Integrity Proof": [
        "$.type: The type property MUST contain the string DataIntegrityProof.",
        "$.cryptosuite: The value of the cryptosuite property MUST be a string that identifies the cryptographic suite.",
        "$.cryptosuite: If the processing environment supports string subtypes, the subtype of the cryptosuite value MUST be the https://w3id.org/security#cryptosuiteString subtype.",
        "$.proofValue: The proofValue property MUST be used, as specified in Section 2.1 Proofs.",
        "Cryptographic suite designers MUST use mandatory proof value properties defined in Section 2.1 Proofs, and MAY define other properties specific to their cryptographic suite."
      ],
      "Algorithms": [
        "Add Proof: Whenever this algorithm encodes strings, it MUST use UTF-8 encoding.",
        "Add Proof: If the algorithm produces an error, the error MUST be propagated.",
        "Add Proof: If one or more of the proof.type, proof.verificationMethod, and proof.proofPurpose values is not set, an error MUST be raised.",
        "Add Proof: If options has a non-null domain item, it MUST be equal to proof.domain or an error MUST be raised.",
        "Add Proof: If options has a non-null challenge item, it MUST be equal to proof.challenge or an error MUST be raised.",
        "Add Proof Set/Chain:Whenever this algorithm encodes strings, it MUST use UTF-8 encoding. ",
        "Add Proof Set/Chain: If a proof with id equal to previousProof does not exist in allProofs, an error MUST be raised.",
        "Add Proof Set/Chain: If any element of previousProof list has an id attribute that does not match the id attribute of any element of allProofs, an error MUST be raised",
        "Verify Proof: When a step says an error MUST be raised, it means that a verification result MUST be returned with a verified value of false and a non-empty errors list.",
        "Verify Proof: If either securedDocument is not a map or securedDocument.proof is not a map, an error MUST be raised",
        "Verify Proof: If one or more of proof.type, proof.verificationMethod, and proof.proofPurpose does not exist, an error MUST be raised",
        "Verify Proof: If expectedProofPurpose was given, and it does not match proof.proofPurpose, an error MUST be raised",
        "Verify Proof: If domain was given, and it does not contain the same strings as proof.domain (treating a single string as a set containing just that string), an error MUST be raised",
        "Verify Proof: If challenge was given, and it does not match proof.challenge, an error MUST be raised",
        "Verify Proof Sets/Chains: If a proof with id does not exist in allProofs, an error MUST be raised",
        "Verify Proof Sets/Chains: If any element of previousProof list has an id attribute that does not match the id attribute of any element of allProofs, an error MUST be raised"
      ],
      "Processing Errors": [
        "The type value of the error object MUST be a URL that starts with the value https://w3id.org/security# and ends with the value in the section listed below.",
        "The code value MUST be the integer code described in the table below."
      ],
      "Verification Methode Binding": [
        "Implementers must ensure that a verification method is bound to a particular controller by going from the verification method to the controller document, and then ensuring that the controller document also contains the verification method."
      ]
    }
  },
  "vc-data-model": {
    "Introduction": {
      "Conformance": [
        "Conforming Document: The relevant normative `MUST` statements in Sections 4. Basic Concepts, 5. Advanced Concepts, and 6. Syntaxes of this document MUST be enforced.",
        "A conforming document MUST be either a verifiable credential with a media type of application/vc or a verifiable presentation with a media type of application/vp.",
        "A conforming document MUST be secured by at least one securing mechanism as described in Section 4.12 Securing Mechanisms.",
        "A conforming issuer implementation MUST include all required properties in the conforming documents it produces.",
        "A conforming issuer implementation MUST secure the conforming documents it produces using a securing mechanism described in Section 4.12 Securing Mechanisms.",
        "A conforming verifier implementation MUST perform verification on a conforming document as described in Section 4.12 Securing Mechanisms.",
        "A conforming verifier implementation MUST check that each required property satisfies the normative requirements for that property.",
        "A conforming verifier implementation MUST produce errors when non-conforming documents are detected."
      ]
    },
    "Basic Concepts": {
      "Contexts": [
        "Verifiable credentials and verifiable presentations MUST include a @context property.",
        "Application developers MUST understand every JSON-LD context used by their application",
        "The value of the @context property MUST be an ordered set where the first item is a URL with the value https://www.w3.org/ns/credentials/v2.",
        "Subsequent items in the ordered set MUST be composed of any combination of URLs and objects, where each is processable as a JSON-LD Context."
      ],
      "Identifiers": [
        "If present, id property's value MUST be a single URL."
      ],
      "Types": [
        "Verifiable credentials and verifiable presentations MUST contain a type property with an associated value.",
        "The value of the type property MUST be one or more terms and absolute URL strings.",
        "Concerning this specification, the following table lists the objects that MUST have a type specified.",
        "Verifiable credential object: `VerifiableCredential` and, optionally, a more specific verifiable credential type.",
        "Verifiable presentation object: `VerifiablePresentation` and, optionally, a more specific verifiable presentation type.",
        "credentialStatus object: A valid credential status type.",
        "termsOfUse object: A valid terms of use type.",
        "evidence object: A valid evidence type",
        "refreshService object: A valid refreshService type. ",
        "credentialSchema object: A valid credentialSchema type. "
      ],
      "Names and Descriptions": [
        "If present, the value of the name property MUST be a string or a language value object as described in 11.1 Language and Base Direction.",
        "If present, the value of the description property MUST be a string or a language value object as described in 11.1 Language and Base Direction."
      ],
      "Issuer": [
        "A verifiable credential MUST have an issuer property.",
        "The value of the issuer property MUST be either a URL or an object containing an id property whose value is a URL"
      ],
      "Credential Subject": [
        "A verifiable credential MUST contain a credentialSubject property.",
        "The value of the credentialSubject property is a set of objects where each object MUST be the subject of one or more claims.",
        "Each claims MUST be serialized inside the credentialSubject property."
      ],
      "Validity Period": [
        "If present, the value of the validFrom property MUST be a [XMLSCHEMA11-2] dateTimeStamp string value.",
        "If a validUntil value also exists, the validFrom value MUST express a point in time that is temporally the same or earlier than the point in time expressed by the validUntil value.",
        "If present, the value of the validUntil property MUST be a [XMLSCHEMA11-2] dateTimeStamp string value",
        "If a validFrom value also exists, the validUntil value MUST express a point in time that is temporally the same or later than the point in time expressed by the validFrom value."
      ],
      "Status": [
        "$.credentialStatus.id: If present, the normative guidance in Section 4.4 Identifiers MUST be followed.",
        "$.credentialStatus.type: The related normative guidance in Section 4.5 Types MUST be followed.",
        "Credential status specifications MUST NOT enable tracking of individuals."
      ],
      "Data Schemas": [
        "The value of the credentialSchema property MUST be one or more data schemas.",
        "Each credentialSchema MUST specify its type.",
        "Each credentialSchema MUST specify an id property that MUST be a URL identifying the schema file."
      ],
      "Verifiable Presentations": [
        "$.id: If present, the normative guidance in Section 4.4 Identifiers MUST be followed.",
        "The type property MUST be present.",
        "One value of this property MUST be VerifiablePresentation.",
        "The related normative guidance in Section 4.5 Types MUST be followed.",
        "$.verifiableCredential: The value MUST be one or more verifiable credential and/or enveloped verifiable credential objects.",
        "$.verifiableCredential: The values MUST NOT be non-object values such as numbers, strings, or URLs.",
        "$.verifiableCredential: These objects MUST express information that is secured using a securing mechanism.",
        "$.holder: If present, the value MUST be either a URL or an object containing an id property."
      ]
    },
    "Advanced Concepts": {
      "Enveloped Verifiable Credentials": [
        "The @context property of the object MUST be present and include a context, such as the base context for this specification, that defines at least the id, type, and EnvelopedVerifiableCredential terms as defined by the base context provided by this specification.",
        "The id value of the object MUST be a data: URL [RFC2397] that expresses a secured verifiable credential using an enveloping security scheme.",
        "The type value of the object MUST be EnvelopedVerifiableCredential."
      ],
      "Enveloped Verifiable Presentation": [
        "The @context property of the object MUST be present and include a context, such as the base context for this specification, that defines at least the id, type, and EnvelopedVerifiablePresentation terms as defined by the base context provided by this specification.",
        "The id value of the object MUST be a data: URL [RFC2397] that expresses a secured verifiable presentation using an enveloping securing mechanism.",
        "The type value of the object MUST be EnvelopedVerifiablePresentation."
      ],
      "Presentations Including Holder Claims": [
        "A verifiable presentation that includes a self-asserted verifiable credential, which is secured only using the same mechanism as the verifiable presentation, MUST include a holder property.",
        "When a self-asserted verifiable credential is secured using the same mechanism as the verifiable presentation, the value of the issuer property of the verifiable credential MUST be identical to the holder property of the verifiable presentation."
      ],
      "Semantic Interoperability": [
        "New terms MUST define a new URL for each term.",
        "Human-readable documentation MUST be published, describing the semantics of and the constraints on the use of each term.",
        "A machine-readable description (that is, a JSON-LD Context document) MUST be published at the URL specified in the @context property for the vocabulary.",
        "This context MUST map each term to its corresponding URL",
        "If a conforming document does not use JSON-LD Contexts that define all terms used, it MUST include the https://www.w3.org/ns/credentials/undefined-terms/v2 as the last value in the @context property."
      ],
      "Integrity of Related Resources": [
        "The value of the relatedResource property MUST be one or more objects of the following form.",
        "id: The value MUST conform to the format defined in Section 4.4 Identifiers.",
        "id: The value MUST be unique among the list of related resource objects.",
        "Each object associated with relatedResource MUST contain at least a digestSRI or a digestMultibase value.",
        "If that resource's content is vital to the validity of that document, the specification MUST produce a validation error unless the resource matches the expected media type and cryptographic digest."
      ],
      "Refreshing": [
        "The value of the refreshService property MUST be one or more refresh services.",
        "Each refreshService value MUST specify its type."
      ],
      "Terms of Use": [
        "The value of the termsOfUse property MUST specify one or more terms of use policies under which the creator issued the credential or presentation.",
        "Each termsOfUse value MUST specify its type."
      ],
      "Evidence": [
        "If present, the value of the evidence property MUST be either a single object or a set of one or more objects.",
        "$.evidence.id: If present, the normative guidance in Section 4.4 Identifiers MUST be followed.",
        "$.evidence.type: The type property is REQUIRED. The related normative guidance in Section 4.5 Types MUST be followed."
      ],
      "Zero-Knowledge Proofs": [
        "Specification authors that create securing mechanisms MUST NOT design them in such a way that they leak information that would enable the verifier to correlate a holder across multiple verifiable presentations to different verifiers."
      ],
      "Representing Time": [
        "Time values that are incorrectly serialized without an offset MUST be interpreted as UTC."
      ],
      "Reserved Extension Points": [
        "In order to avoid collisions regarding how the following properties are used, implementations MUST specify a type property in the value associated with the reserved property.",
        "confidenceMethod: The associated vocabulary URL MUST be https://www.w3.org/2018/credentials#confidenceMethod.",
        "renderMethod: The associated vocabulary URL MUST be https://www.w3.org/2018/credentials#renderMethod."
      ],
      "Ecosystem Compatibility": [
        "MUST identify whether the transformation to this data model is one-way-only or round-trippable.",
        "MUST preserve the @context values when performing round-trippable transformation.",
        "MUST result in a conforming document when transforming to the data model described by this specification.",
        "MUST specify a registered media type for the input document."
      ],
      "Securing Mechanism Specifications": [
        "Securing mechanism specifications MUST document normative algorithms that provide content integrity protection for conforming documents.",
        "Securing mechanism specifications MUST provide a verification algorithm that returns the information in the conforming document that has been secured, in isolation, without including any securing mechanism information, such as proof or JOSE/COSE header parameters and signatures.",
        "A verification algorithm MUST provide an interface that receives a media type (string inputMediaType) and input data (byte sequence or map inputData).",
        "A securing mechanism specification that creates a new type of embedded proof MUST specify a property that relates the verifiable credential or verifiable presentation to a proof graph.",
        "Embedded Proof: The securing mechanism MUST define all terms used by the proof graph.",
        "Embedded Proof: The securing mechanism MUST secure all graphs in the verifiable credential or the verifiable presentation, except for any proof graphs securing the verifiable credential or the verifiable presentation itself."
      ]
    },
    "Syntaxes": {
      "Restrictions on JSON-LD": [
        "JSON-LD compacted document form MUST be utilized for all representations of the data model using the application/vc or application/vp media type."
      ]
    },
    "Algorithms": {
      "Verification": [
        "This section contains an algorithm that conforming verifier implementations MUST run when verifying a verifiable credential or a verifiable presentation.",
        "The verifyProof function MUST implement the interface described in 5.13 Securing Mechanism Specifications."
      ],
      "Problem Details": [
        "The type property MUST be present and its value MUST be a URL identifying the type of problem.",
        "code: If present, its value MUST be an integer that identifies the type of the problem.",
        "The title property MUST be present and its value SHOULD provide a short but specific human-readable string for the problem.",
        "The detail property MUST be present and its value SHOULD provide a longer human-readable string for the problem."
      ]
    },
    "Internationalization Considerations": {
      "Language and Base Direction": [
        "When the language value object is used in place of a string value, the object MUST contain a @value property whose value is a string.",
        "The language value object MUST NOT include any other keys beyond @value, @language, and @direction."
      ]
    },
    "Contexts, Vocabularies, Types, and Credential Schemas": {
      "Base Context": [
        "Implementations MUST treat the base context value, located at https://www.w3.org/ns/credentials/v2, as already retrieved.",
        "Implementations that apply the base context above, as well as other contexts and values in any @context property, during operations such as JSON-LD Expansion or transformation to RDF, are expected to do so without experiencing any errors. If such operations are performed and result in an error, the verifiable credential or verifiable presentation MUST result in a verification failure."
      ],
      "Vocabularies": [
        "Implementations that depend on RDF vocabulary processing MUST ensure that the following vocabulary URLs used in the base context ultimately resolve to the following files when loading the JSON-LD serializations, which are normative."
      ]
    }
  },
  "vc-bitstring-status-list": {
    "Introduction": {
      "Conformance": [
        "Conforming processors MUST produce errors when non-conforming documents are consumed."
      ]
    },
    "Data Model": {
      "BitstringStatusListEntry": [
        "Any expression of the data model in this section MUST be expressed in a conforming verifiable credential as defined in [VC-DATA-MODEL-2.0].",
        "$.credentialStatus.id: It MUST NOT be the URL for the status list.",
        "$.credentialStatus.type: The type property MUST be BitstringStatusListEntry.",
        "$.credentialStatus.statusPurpose: The purpose of the status entry MUST be a string.",
        "$.credentialStatus.statusPurpose: While the value of the string is arbitrary, the following values MUST be used for their intended purpose.",
        "$.credentialStatus.statusListIndex: The statusListIndex property MUST be an arbitrary size integer greater than or equal to 0, expressed as a string in base 10.",
        "$.credentialStatus.statusListCredential: The statusListCredential property MUST be a URL to a verifiable credential.",
        "$.credentialStatus.statusListCredential: When the URL is dereferenced, the resulting verifiable credential MUST have type property that includes the BitstringStatusListCredential value.",
        "$.credentialStatus.statusSize: If statusSize is not present as a property of the credentialStatus, then statusSize MUST be processed as 1.",
        "$.credentialStatus.statusSize: If present, statusSize MUST be an integer greater than zero.",
        "$.credentialStatus.statusSize: If statusSize is provided and is greater than 1, then the property credentialStatus.statusMessage MUST be present",
        "$.credentialStatus.statusSize: If statusSize is provided and is greater than 1, the number of status messages MUST equal the number of possible values.",
        "$.credentialStatus.statusMessage: If present, the statusMessage property MUST be an array.",
        "$.credentialStatus.statusMessage: If present, the length MUST equal the number of possible status messages indicated by statusSize.",
        "$.credentialStatus.statusMessage: statusMessage array MUST have 2 elements if statusSize has 1 bit, 4 elements if statusSize has 2 bits, 8 elements if statusSize has 3 bits, etc.",
        "$.credentialStatus.statusMessage: statusMessage MUST be present if statusSize is greater than 1.",
        "$.credentialStatus.statusMessage: If the statusMessage array is present, each element MUST contain the status property, a string representing the hexadecimal value of the status prefixed with 0x ",
        "$.credentialStatus.statusMessage: If the statusMessage array is present, each element MUST contain the message property, a string used by software developers to assist with debugging.",
        "$.credentialStatus.statusReference: If present, its value MUST be a URL or an array of URLs [URL] which dereference to material related to the status."
      ],
      "BitstringStatusListCredential": [
        "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.",
        "$.id: The verifiable credential that contains the status list MUST express a type property that includes the BitstringStatusListCredential value.",
        "$.credentialSubject.id: The type of the credential subject, which is the status list, MUST be BitstringStatusList.",
        "$.credentialSubject.statusPurpose: The value of the purpose property of the status entry, statusPurpose, MUST be one or more strings.",
        "$.credentialSubject.statusPurpose: While the value of each string is arbitrary, the following values MUST be used for their intended purpose.",
        "$.credentialSubject.statusPurpose(message): The status message descriptions MUST be defined in credentialSubject.statusMessages.",
        "$.credentialSubject.statusPurpose(message): credentialSubject.statusSize MUST be specified when this statusPurpose value is used.",
        "$.credentialSubject.encodedList: The encodedList property of the credential subject MUST be a Multibase-encoded base64url (with no padding) [RFC4648] representation of the GZIP-compressed [RFC1952] bitstring values for the associated range of verifiable credential status values.",
        "$.credentialSubject.encodedList: The uncompressed bitstring MUST be at least 16KB in size.",
        "$.credentialSubject.encodedList: The bitstring MUST be encoded such that the first index, with a value of zero (0), is located at the left-most bit in the bitstring and the last index, with a value of one less than the length of the bitstring (bitstring_length - 1), is located at the right-most bit in the bitstring.",
        "$.credentialSubject.ttl: If not present, implementers MUST use a value of 300000 for this property.",
        "$.credentialSubject.ttl: A verifier MUST NOT use a cached BitstringStatusListCredential that was cached for more than the ttl duration prior to the start of verification operation on a verifiable credential."
      ]
    },
    "Algorithms": {
      "": [
        "If an implementation of any of the algorithms in this section processes a property defined in Section 2. Data Model whose value is malformed due to not complying with associated `MUST` statements, a MALFORMED_VALUE_ERROR MUST be raised."
      ],
      "Generate Algorithm": [
        "The following process, or one generating the exact output, MUST be followed when producing a BitstringStatusListCredential."
      ],
      "Validate Algorithm": [
        "The following process, or one generating the exact output, MUST be followed when validating a verifiable credential that is contained in a BitstringStatusListCredential.",
        "If the credentialIndex multiplied by the size is a value outside of the range of the bitstring, a RANGE_ERROR MUST be raised.",
        "If a mechanism to dereference the status list as of a particular point in time is supported, and if query parameters are supported by the URL scheme, then the name of the query parameter MUST be timestamp and the value MUST be a valid URL-encoded [XMLSCHEMA11-2] dateTimeStamp string value.",
        "The result of dereferencing such a timestamp-parameterized URL MUST be either a status list credential containing the status list as it existed at the given point in time, or a STATUS_RETRIEVAL_ERROR."
      ],
      "Bitstring Generation Algorithm": [
        "The following process, or one generating the exact output, MUST be followed when generating a status list bitstring."
      ],
      "Bitstring Expansion Algorithm": [
        "The following process, or one generating the exact output, MUST be followed when expanding a compressed status list bitstring."
      ],
      "Processing Errors": [
        "The type value of the error object MUST be a URL that starts with the value https://www.w3.org/ns/credentials/status-list# and ends with the value in the section listed below.",
        "The code value MUST be the integer code described in the table below."
      ]
    }
  }
}