Skip to content

Commit

Permalink
Consolidate wording about cawg. labels (#190)
Browse files Browse the repository at this point in the history
  • Loading branch information
scouten-adobe authored Oct 8, 2024
1 parent 13178aa commit 8af578c
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 8 deletions.
38 changes: 30 additions & 8 deletions docs/modules/ROOT/pages/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The link:https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specifica

This specification describes a _<<C2PA assertion>>_ referred to here as the *<<_identity_assertion,identity assertion>>* that can be added to a _<<C2PA Manifest>>_ 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 _<<C2PA asset>>’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].

Expand Down Expand Up @@ -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 _<<C2PA asset>>_ 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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions docs/modules/ROOT/partials/version-history.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

0 comments on commit 8af578c

Please sign in to comment.