From 8af578cfe7bcb785dff8265087425258aeb02081 Mon Sep 17 00:00:00 2001 From: Eric Scouten Date: Tue, 8 Oct 2024 15:27:39 -0700 Subject: [PATCH] Consolidate wording about `cawg.` labels (#190) --- docs/modules/ROOT/pages/index.adoc | 38 +++++++++++++++---- .../ROOT/partials/version-history.adoc | 4 ++ 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index e58b8b2..cb58e80 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -9,7 +9,7 @@ The link:https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specifica This specification describes a _<>_ referred to here as the *<<_identity_assertion,identity assertion>>* that can be added to a _<>_ to enable a _<<_credential_holder,credential holder>>_ to prove control over a digital identity and to use that identity to document the _<<_named_actor,named actor’s>>_ role(s) in the _<>’s_ lifecycle. -Version 1.1 (adding identity claims aggregation) *Draft 02 October 2024* · xref:_version_history[] +Version 1.1 (adding identity claims aggregation) *Draft 08 October 2024* · xref:_version_history[] IMPORTANT: This specification differs from the link:https://creator-assertions.github.io/identity/1.0/[1.0 version] primarily in the addition of xref:_identity_claims_aggregation[xrefstyle=full]. @@ -438,9 +438,7 @@ If present, the value for `role` MUST be a non-empty CBOR array of non-empty tex | `cawg.translator` | The _<<_named_actor,named actor>>_ has adapted of this _<>_ from a similar work in another language. |======================= -Other CBOR text string values MAY be used in `role` with the understanding that they may not be well understood by *<<_identity_assertion,identity assertion>>* consumers. CBOR text string values for `role` that begin with the prefix `cawg.` are reserved for the use of the Creator Assertions Working Group and MUST NOT be used unless defined in a this or a future version of this specification. - -IMPORTANT: Future minor version updates (1.1, 1.2, etc.) to this specification MAY define new values for `role` using the `cawg.` prefix. +Other CBOR text string values MAY be used for `role`, subject to the restrictions described in xref:_labels[xrefstyle=full]. === CBOR schema @@ -514,6 +512,32 @@ An example in https://www.rfc-editor.org/rfc/rfc8949.html#name-diagnostic-notati } ---- +=== Labels + +Several data types in this specification have labels that can be defined either in this specification or by an external entity. + +Labels are non-empty string values organized into namespaces using a period (`.`) as a separator. The namespace component of the label can be an entity or a reference to a well-established standard. (See ABNF below.) + +Labels defined by the CAWG will begin with `cawg.`. All labels beginning with `cawg.` that are not defined in the current version of the specification are reserved for the future use of the CAWG and MUST NOT be assigned by any other entity. Future minor version updates (1.2, 1.3, etc.) to this specification MAY define new values for any label using the `cawg.` prefix. + +Entity-specific labels (i.e. those not defined by CAWG) SHALL begin with the Internet domain name for the entity similar to how Java packages are defined (e.g., `com.litware`, `net.fineartschool`). + +[[abnf_for_labels]] +[source,abnf] +.ABNF for labels +---- +namespaced-label = qualified-namespace label +qualified-namespace = "cawg" / entity +entity = entity-component *( "." entity-component ) +entity-component = 1( DIGIT / ALPHA ) *( DIGIT / ALPHA / "-" / "_" ) +label = 1*( "." label-component ) +label-component = 1( DIGIT / ALPHA ) *( DIGIT / ALPHA / "-" / "_" ) +---- + +The period-separated components of a label follow the variable naming convention (`[a-zA-Z][a-zA-Z0-9_-]*`) specified in the POSIX or C locale, with the restriction that the use of a repeated underscore character (`__`) is reserved for labelling multiple assertions of the same type. + +WARNING: While the use of labels defined by external entities is permitted, implementers should be aware that such labels may not be widely understood by other implementations. + == Creating the identity assertion === Presenting the `signer_payload` data structure for signature @@ -749,7 +773,7 @@ The *<<_identity_assertion,identity assertion>>* allows multiple signature types The signature type is represented by the `signer_payload.sig_type` field. Some credential types are described in this specification. It is strongly recommended that *<<_identity_assertion,identity assertion>>* validators be prepared to read all of the signature types described in this specification. -Other specifications MAY define additional `signer_payload.sig_type` values and the corresponding definition of `signature` with the understanding that some *<<_identity_assertion,identity assertion>>* validators may not be prepared to understand such assertions. Values of `signer_payload.sig_type` that begin with the prefix `cawg.` are reserved for use of the Creator Assertions Working Group and MUST NOT be used in any specification not produced by this group. +Other specifications MAY define additional `signer_payload.sig_type` values and the corresponding definition of `signature`, subject to restrictions described in xref:_labels[xrefstyle=full]. [IMPORTANT] .Credential types in minor version updates @@ -992,9 +1016,7 @@ The `verifiedIdentities[?].type` property MUST be present and MUST be a non-empt | `cawg.crypto_wallet` | The _<<_named_actor,named actor>>_ has demonstrated control over an account (typically a crypto-wallet) hosted by the _<<_identity_provider,identity provider>>._ |======================= -Other string values MAY be used in `verifiedIdentities[?].type` with the understanding that they may not be well understood by *<<_identity_assertion_consumer,identity assertion consumers>>.* String values for `verifiedIdentities[?].type` that begin with the prefix `cawg.` are reserved for the use of the Creator Assertions Working Group and MUST NOT be used unless defined in a this or a future version of this specification. - -IMPORTANT: Future minor version updates (1.1, 1.2, etc.) to this specification MAY define new values for `verifiedIdentities[?].type` using the `cawg.` prefix. +Other string values MAY be used in `verifiedIdentities[?].type`, subject to restrictions described in xref:_labels[xrefstyle=full]. [#vc-credentialsubject-verifiedidentity-name] ====== Display name diff --git a/docs/modules/ROOT/partials/version-history.adoc b/docs/modules/ROOT/partials/version-history.adoc index 6aac3f1..84c684c 100644 --- a/docs/modules/ROOT/partials/version-history.adoc +++ b/docs/modules/ROOT/partials/version-history.adoc @@ -108,3 +108,7 @@ _This section is non-normative._ *02 October 2024* * (Clerical) Add anchor references pointing to workflows within verifiable presentation example. + +*08 October 2024* + +* Consolidate wording about `cawg.` and other externally-defined labels