From 4cee8fdf062a72a24f6bea3f10f9d2eacc9fb194 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Fri, 17 Jan 2025 10:20:06 +0100 Subject: [PATCH 01/46] chore: remove old rc version which is outdated --- docs/v1.1.0-rc.md | 604 ---------------------------------------------- 1 file changed, 604 deletions(-) delete mode 100644 docs/v1.1.0-rc.md diff --git a/docs/v1.1.0-rc.md b/docs/v1.1.0-rc.md deleted file mode 100644 index 310d580..0000000 --- a/docs/v1.1.0-rc.md +++ /dev/null @@ -1,604 +0,0 @@ ---- -title: OCA Spec - 1.1.0-rc -description: Official OCA specification - ---- -# Overlays Capture Architecture Specification - -## Version 1.1.0-rc -### Changelog - -- Introduce Credential Overlay -- Introduce Form Overlay - - -## Introduction - -Overlays Capture Architecture (OCA) offers a solution to harmonisation between -data models and data representation formats. Primarily devised for semantic -object interoperability and privacy compliant data sharing, OCA is a proposed -global standard for data capture that promises to significantly enhance the -ability to define, manage, and use data in terms of simplicity, accuracy, and -allocation of resources.Overlays Capture Architecture (OCA) offers a solution to -harmonisation between data models and data representation formats. Primarily -devised for semantic object interoperability and privacy compliant data sharing, -OCA is a proposed global standard for data capture that promises to -significantly enhance the ability to define, manage, and use data in terms of -simplicity, accuracy, and allocation of resources. - -OCA represents a form (domain-agnostic) and schema (domain-specific) as a -multi-dimensional object consisting of a stable [Capture Base](#capture-base) and interoperable -Overlays. By introducing Overlays as task-oriented linked objects within the OCA -stack, the architecture offers an optimal level of both efficiency and -interoperability in alignment with FAIR principles. - - -![OCA overview](/images/oca_overview.png) - -The [FAIR Data Principles](https://www.nature.com/articles/sdata201618) -(Wilkinson et al., 2016), a set of guiding principles to make data findable, -accessible, interoperable, and reusable; guide scientific data management and -stewardship; and are relevant to all digital economy stakeholders. - -## Capture base - -A Capture Base is a stable base object that defines a single dataset in its -purest form, providing a standard base to harmonise data. The object defines -[attribute names](#attribute-name) and [types](). The construct also includes a flagging block, -allowing the issuer of a form or schema to flag any attributes where identifying -information about entities\* may be captured. With [flagged attributes](), all -corresponding data can be treated as high-risk throughout the data lifecycle and -encrypted or removed at any stage, reducing the risk of re-identification -attacks against blinded datasets. - - -```json -{ - "type": "spec/capture_base/1.0", - "classification": "GICS:45102010", - "attributes": { - "dateOfBirth": "Date", - "dateOfExpiry": "Date", - "dateOfIssue": "Date", - "documentCode": "Text", - "documentNumber": "Text", - "documentType": "Text", - "fullName": "Text", - "issuedBy": "Text", - "issuingState": "Text", - "issuingStateCode": "Text", - "nationality": "Text", - "optionalData": "Text", - "optionalDocumentData": "Text", - "optionalPersonalData": "Text", - "personalNumber": "Text", - "photoImage": "Binary", - "placeOfBirth": "Text", - "primaryIdentifier": "Text", - "secondaryIdentifier": "Text", - "sex": "Text", - "signatureImage": "Binary" - }, - "flagged_attributes": [ - "documentNumber", - "fullName", - "primaryIdentifier", - "secondaryIdentifier", - "dateOfBirth", - "personalNumber", - "placeOfBirth", - "optionalPersonalData", - "optionalDocumentData", - "signatureImage", - "photoImage", - "optionalData" - ] -} -``` - - -### Attribute name - -An [attribute name](#attribute-name) is a string that identifies an attribute. - - -### Attribute type - -An attribute type determines the attribute's syntax and how attributes of that -type are compared and sorted. A Capture Base recognises seven core attribute -types: - -- **Text**: a data type that defines a human-readable sequence of characters and - the words they form, subsequently encoded into computer-readable formats such - as ASCII. -- **Numeric**: a data type that defines anything of, relating to, or containing - numbers. The numbering system consists of ten different digits: 0, 1, 2, 3, 4, - 5, 6, 7, 8, and 9. -- **Reference**: a data type that defines a self-addressing identifier (SAI) - that references a set of attributes through its associated parent. SAID is an - identifier that is deterministically generated from and embedded in the - content it identifies, making it and its data mutually tamper-evident. -- **Boolean**: a data type where the data only has two possible variables: true - or false. In computer science, Boolean is an identification classifier for - working out logical truth values and algebraic variables. -- **Binary**: a data type that defines a binary code signal, a series of - electrical pulses representing numbers, characters, and performed operations. - Based on a binary number system, each digit position represents a power of two - (e.g., 4, 8, 16, etc.). In binary code, a set of four binary digits or bits - represents each decimal number (0 to 9). Each digit only has two possible - states: off and on (usually symbolised by 0 and 1). Combining basic Boolean - algebraic operations on binary numbers makes it possible to represent each of - the four fundamental arithmetic operations of addition, subtraction, - multiplication, and division. -- **DateTime**: a data type that defines the number of seconds or clock ticks - that have elapsed since the defined epoch for that computer or platform. - Common formats (see 'Format Overlay') include dates (e.g., YYYY-MM-DD), times - (e.g., hh:mm:ss), dates and times concatenated (e.g., - YYYY-MM-DDThh:mm:ss.sss+zz:zz), and durations (e.g., PnYnMnD). -- **Array** [attribute type]: a data type that defines a structure that holds - several data items or elements of the same data type. When you want to store - many pieces of data that are related and have the same data type, it is often - better to use an array instead of many separate variables (e.g. array[text], - array[numeric], etc.). - -### Flagged attributes - -Any attributes defined in a Capture Base that may contain identifying -information about entities\* (i.e., personally identifiable information (PII) or -quasi-identifiable information (QII)) can be flagged. The [Blinding Identity -Taxonomy](https://docs.kantarainitiative.org/Blinding-Identity-Taxonomy-Report-Version-1.0.pdf) -(BIT), a definitive list of what constitutes identifying information, is -available at -[here](https://docs.kantarainitiative.org/Blinding-Identity-Taxonomy-Report-Version-1.0.pdf). - -\**Note*: Entities may be (but not necessarily) natural persons. - -## Overlays - -Overlays are cryptographically-linked objects that provide layers of -task-oriented contextual information to a [Capture Base](#capture-base). Any actor interacting -with a published Capture Base can use Overlays to transform how information is -displayed to a viewer or guide an agent in applying a custom process to captured -data. - - -## Semantic Overlays - -Semantic overlays provide contextual meaning to describe objects and their relationships, including attributes, forms, and schemas. - -![Semantic](/images/rugby-semantic.png) - -Figure 3.1. In a balanced network, semantic overlays determine the meaning and use of what is put in, taken in, or operated on by any process or system. - - -### Character Encoding Overlay - -A Character Encoding Overlay defines the process of assigning numbers to graphical characters, especially the written characters of human language, allowing them to be stored, transmitted, and transformed using digital computers. Character encoding using internationally accepted standards permits worldwide interchange of text in electronic form. The default character set is UTF-8, which is the most common encoding for the World Wide Web, accounting for 98% of all web pages, and up to 100.0% for some languages, as of 2021. - -Examples: ASCII, ISO-8859-1, UTF-8, etc. - -```json -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/character_encoding/1.0", - "default_character_encoding": "utf-8", - "attr_character_encoding": { - "dateOfBirth": "utf-8", - "dateOfExpiry": "utf-8", - "dateOfIssue": "utf-8", - "documentCode": "utf-8", - "documentNumber": "utf-8", - "documentType": "utf-8", - "fullName": "utf-8", - "issuedBy": "utf-8", - "issuingState": "utf-8", - "issuingStateCode": "utf-8", - "nationality": "utf-8", - "optionalData": "utf-8", - "optionalDocumentData": "utf-8", - "optionalPersonalData": "utf-8", - "personalNumber": "utf-8", - "photoImage": "base64", - "placeOfBirth": "utf-8", - "primaryIdentifier": "utf-8", - "secondaryIdentifier": "utf-8", - "sex": "utf-8", - "signatureImage": "base64" - } -} -``` -Code snippet for a Character Encoding Overlay - -### Format Overlay - -A Format Overlay defines an input and display format for numeric and date -fields. The data format enables the conversion of the input buffer to the -program variable and displays program variable data to form fields. - -Examples: YYYY-MM-DD, (?<=:25:)\d{8}(?=/), (\d+(,\d*)?)|(,\d+), etc. - -```json -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/format/1.0", - "attr_formats": { - "dateOfBirth": "YYnMMnDD", - "dateOfExpiry": "YYnMMnDD", - "dateOfIssue": "YYnMMnDD", - "documentCode": "P[A-Z0-9]{1}", - "documentNumber": "[A-Z0-9]{9}", - "issuingStateCode": "[A-Z]{3}", - "personalNumber": "[A-Z0-9]{14}", - "photoImage": "image/jpeg", - "signatureImage": "image/jpeg" - } -} - -``` -Code snippet for a Format Overlay - -### Information Overlay -[language-specific object] - -An Information Overlay defines attribute field descriptions and usage notes to -assist the data entry process. - -```json -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/information/1.0", - "language": "en", - "attr_information": { - "dateOfBirth": "Holder’s date of birth as recorded by the issuing State or organization. If the date of birth is unknown, see Doc 9303-3 for guidance.", - "dateOfExpiry": "Date of expiry of the MRP. For additional details see Doc 9303-3.", - "dateOfIssue": "For details see Doc 9303-3.", - "documentCode": "Capital letter P to designate an MRP. One additional capital letter may be used, in the character position after the letter P and at the discretion of the issuing State or organization, to designate other types of passports such as MRP issued to diplomatic staff, an MRP issued for travel on government business, or a passport issued for a special purpose.", - "documentNumber": "As given by the issuing State or organization to uniquely identify the document from all other MRTDs issued by the State or organization. For additional details see Doc 9303-3.", - "documentType": "The word for “passport” in the language of the issuing State or organization.", - "fullName": "The full name of the holder, as identified by the issuing State or organization. For additional details see Doc 9303-3.", - "issuedBy": "Authority or issuing organization for the MRP. This field shall be used to indicate the issuing authority or issuing organization and, optionally, its location, which may be personalized within this field. For additional details see Doc 9303-3.", - "issuingState": "The name of the State or organization responsible for issuing the MRP shall be displayed in full.", - "issuingStateCode": "As abbreviated in the three-letter code specified in Doc 9303-3.", - "nationality": "For details see Doc 9303-3.", - "optionalData": "Additional optional data elements at the discretion of the issuing State or organization. For additional details see Doc 9303-3.", - "optionalDocumentData": "Optional data elements relating to the document. For additional details see Doc 9303-3.", - "optionalPersonalData": "Optional personal data elements e.g. personal identification number or fingerprint, at the discretion of the issuing State or organization. If a fingerprint is included in this field, it should be presented as a 1:1 representation of the original. If a date is included, it shall follow the form of presentation described in Doc 9303-3.", - "personalNumber": "Field optionally used for personal identification number given to holder by the issuing State or organization. For additional details see Doc 9303-3. ", - "photoImage": "This field shall contain a portrait of the holder. The portrait shall not be larger than 45.0 mm x 35.0 mm_x005F_x000B_(1.77 in x 1.38 in) nor smaller than 32.0 mm x 26.0 mm (1.26 in x 1.02 in). The position of the field concerned shall be aligned to the left of Zones II, III and IV. See Doc 9303-3 for additional specifications for the portrait.", - "placeOfBirth": "Field optionally used for city and State of the holder’s birthplace. Refer to Doc 9303-3 for further details. ", - "primaryIdentifier": "Predominant component(s) of the name of the holder as described in Doc 9303-3. In cases where the predominant component(s) of the name of the holder (e.g. where this consists of composite names) cannot be shown in full or in the same order, owing to space limitations of Field(s) 06 and/or 07 or national practice, the most important component(s) (as determined by the State or organization) of the primary identifier shall be inserted.", - "secondaryIdentifier": "Secondary component(s) of the name of the holder as described in Doc 9303-3. The most important component(s) (as determined by the State or organization) of the secondary identifier of the holder shall be inserted in full, up to the maximum dimensions of the field frame. Other components, where necessary, may be represented by initials. Where the holder’s name has only predominant component(s), this data field shall be left blank. A State may optionally utilize the whole zone comprising Fields 06 and 07 as a single field. In such a case, the primary identifier shall be placed first, followed by a comma and a space, followed by the secondary identifier. ", - "sex": "Sex of the holder, to be specified by use of the single initial commonly used in the language of the State or organization where the document is issued and, if translation into English, French or Spanish is necessary, followed by an oblique and the capital letter F for female, M for male, or X for unspecified.", - "signatureImage": "At the discretion of the issuing State or organization, the signature or usual mark may be located in Zone VI. The size of the field to be allocated to the signature or usual mark on the adjoining page shall be at the discretion of the issuing State or organization, subject to the overall dimensional limits of the MRP. For additional details see Doc 9303-3." - } -} -``` -Code snippet for an Information Overlay - - -### Label Overlay -[language-specific object] - -A Label Overlay defines category and display labels for attributes. For example, -given an attribute named firstName, you may want to display a label First Name -which is more user-friendly when displayed to end users in places such as form -inputs and error messages. - -```json -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/label/1.0", - "language": "en", - "attr_labels": { - "dateOfBirth": "Date of birth", - "dateOfExpiry": "Date of expiry", - "dateOfIssue": "Date of issue", - "documentCode": "Document code", - "documentNumber": "Passport Number", - "documentType": "Document", - "fullName": "Name", - "issuedBy": "Authority or issuing organization", - "issuingState": "Issuing State or organization (in full)", - "issuingStateCode": "Issuing State or organization (in code)", - "nationality": "Nationality", - "optionalData": "Optional data elements", - "optionalDocumentData": "Optional document data elements", - "optionalPersonalData": "Optional personal data elements", - "personalNumber": "Personal number", - "photoImage": "Identification feature", - "placeOfBirth": "Place of birth", - "primaryIdentifier": "Primary Identifier", - "secondaryIdentifier": "Secondary Identifier", - "sex": "Sex", - "signatureImage": "Holder’s signature or usual mark" - }, - "attr_categories": [ - "_cat-1_", - "_cat-2_", - "_cat-3_", - "_cat-4_", - "_cat-5_", - "_cat-6_" - ], - "cat_labels": { - "_cat-1_": "Mandatory header", - "_cat-2_": "Mandatory and optional personal data elements", - "_cat-3_": "Mandatory and optional document data elements", - "_cat-4_": "Mandatory holder’s signature or usual mark (original or reproduction)", - "_cat-5_": "Mandatory identification feature", - "_cat-6_": "Optional data elements" - }, - "cat_attributes": { - "_cat-1_": [ - "issuingState", - "documentType", - "documentCode", - "issuingStateCode", - "documentNumber" - ], - "_cat-2_": [ - "fullName", - "primaryIdentifier", - "secondaryIdentifier", - "nationality", - "dateOfBirth", - "personalNumber", - "sex", - "placeOfBirth", - "optionalPersonalData" - ], - "_cat-3_": [ - "dateOfIssue", - "issuedBy", - "dateOfExpiry", - "optionalDocumentData" - ], - "_cat-4_": [ - "signatureImage" - ], - "_cat-5_": [ - "photoImage" - ], - "_cat-6_": [ - "optionalData" - ] - } -} -``` - -Code snippet for a Label Overlay - -### Meta Overlay -[language-specific object] - -A Meta Overlay defines the descriptive information about a schema or form. It is -used for discovery and identification and includes elements such as form name -and description. - -```json -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/meta/1.0", - "language": "en", - "name": "VIZ for Digital Passport", - "description": "A form to be used for capturing Visual Inspection Zone data for a Digital Passport" -} - -``` -Code snippet for a Meta Overlay - -### Standards Overlay - -A Standards Overlay defines a documented agreement or technical specification -published by a standards organisation used to represent, format, define, -structure, tag, transmit, manipulate, use, and manage data. - -Examples: ISO 3166-1 alpha-2, SNOMED CT, IETF RFC 2246 (1999), etc. - - -```json -TODO - -``` -Code snippet for a Standards Overlay - -## Inputs Overlays - -Inputs overlays provide predefined inputs for data attestations, including -claims, credentials, and records. - -![OCA Input](/images/rugby-input.png) - -In a balanced network, inputs overlays determine what is put in, taken in, or -operated on by any process or system. - -### Cardinality Overlay - -A Cardinality Overlay defines the relational information between attributes, -which later models need when modelling the actual table architecture. For -example, without knowing the relationship cardinality, one cannot model the -tables and key restrictions between them. Typical uses include setting data -entry requirements on specific fields (i.e., Mandatory or Optional) and setting -conditional attribute dependencies according to the chosen entries of a parent -attribute. - -```json -TODO - -``` -Code snippet for a Cardinality Overlay - -### Conditional Overlay - -A Conditional Overlay defines conditional logic where input conditions for one -attribute cause a process change to another. It also allows the application of a -child schema based on the outcome of a parent schema, much like the if/then/else -constructs seen in traditional programming languages. - -### Entry Code Overlay - -An Entry Code Overlay defines the entry keys in a series of key-value pairs -stored in a code table (aka lookup table) or dataset. The key is a unique -identifier that points to its associated value. - -Examples: CA, CA-BC, NA, etc. - -```json -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/entry_code/1.0", - "attr_entry_codes": { - "documentType": [ - "PASSPORT" - ], - "issuingState": "EWSSp1MZQfVWl-u4l4eDprRp-bLE-xLe0gSTNVwkuqNA", - "issuingStateCode": "EWSSp1MZQfVWl-u4l4eDprRp-bLE-xLe0gSTNVwkuqNA", - "nationality": "EcOqelFTDay0reu_CesOIUfWVF7htg4IvSOrrXuIMaXU", - "sex": [ - "F", - "M", - "X" - ] - } -} - -``` - -Code snippet for an Entry Code Overlay - -### Entry Overlay -[language-specific object] - -An Entry Overlay defines the entry values in a series of key-value pairs stored -in a code table (aka lookup table) or dataset. A value is either the identified -data or a pointer to that data. - -Examples: Canada, British Columbia, North America, etc. - - -```json -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/entry/1.0", - "language": "en", - "attr_entries": { - "documentType": { - "PASSPORT": "PASSPORT" - }, - "issuingState": "ECfBoOwdcHhQfNtWA5qTKOo9egoxHKXxby6R8Jujpk-o", - "issuingStateCode": "EnmO60xL2IsIv-_AC2PgLdJtzqsfuNqa8BihsiNWgz5o", - "nationality": "EAr0uvi1743P2VXXqd08a-yX8K_aejHCkdjaW8lWZ_xw", - "sex": { - "F": "Female", - "M": "Male", - "X": "Unspecified" - } - } -} -``` - -### Unit Overlay - -A Unit Overlay defines the units of measurement adopted by convention or law, -used as a standard for measuring the same kind of quantity. The recommended -system to use is the International System of Units (SI), French Système -International d’Unités, an international decimal system of weights and measures -derived from and extending the metric system of units. Adopted by the 11th -General Conference on Weights and Measures (CGPM) in 1960, it is abbreviated SI -in all languages. To date, the SI comprises seven base units: the meter (m), the -kilogram (kg), the second (s), the ampere (A), the kelvin (K), the candela (cd) -and the mole (mol). More information on the SI is available -[here](https://www.bipm.org/en/measurement-units). - -![SI](/images/si.png) - -The seven defining constants of the SI - -```json -TODO -``` -Code snippet for a Unit Overlay - - -## Transformation Overlays -  -Transformation overlays provide information to convert data from one format or -structure to another, such as raw data to processed, or unstructured to -structured. - -### Mapping Overlay -  -A Mapping Overlay defines attribute mappings between two distinct data models. -Data mapping provides a preliminary step for data integration tasks, including -data transformation or data mediation between a data source and a destination or -consolidation of multiple databases into a single database and identifying -redundant columns of data for consolidation or elimination. - - -### Masking Overlay -  -A Masking Overlay defines the process of masking or obfuscating sensitive data -so that it is of no or little value to unauthorised intruders while still being -usable by software or authorised personnel. The main reason for applying masking -to a data field is to protect personally identifiable, quasi-identifiable, -sensitive personal, or commercially sensitive data. - -### Subset Overlay -  -A Subset Overlay defines a customised version of a published schema or form -containing a subset of source attributes, including their properties, types, -codes, and relationship dependencies required for the information exchange. - -## Presentation Overlays - -Presentation overlays provide information to display data objects at the -application layer, including forms and credentials. - - -### Credential Layout Overlay - -A Credential Layout Overlay defines presentation information required by an -application to display a digital credential. - - -```json -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/credential_layout/1.0", - "layout": "config:\n width: 980px\n height: 1400px\n style: \"@import url('https://fonts.googleapis.com/css2?family=Nanum+Gothic:wght@700&display=swap'); @font-face { font-family: 'Euphemia'; src: url('https://data-vault.argo.colossi.network/api/v1/files/zQmVwGQNiz8nGHJW1ZvgCyi1Sx1WZeGwJRfdyLedxUJG1Np'); } @font-face { font-family: 'OCRB 10 Pitch BT'; src: url('https://data-vault.argo.colossi.network/api/v1/files/zQmPWK7khoAebbJDZsmgQgjyH2hsThYYPBKWbSbV5tn8NrC'); }\"\npages:\n - config:\n style: \"width: 980px; height: 700px; margin: 0;\"\n background_image: SAI:zQmf4NGbt4q7ufjK1dNaQdMaJgGLXigAYJWXGc1cjaASXxc\n name: Page 0\n elements:\n - type: row\n config:\n style: \"height: 32px;\"\n elements:\n - type: row\n elements:\n - type: col\n size: 4\n config:\n style: \"padding-right: 0;\"\n elements:\n - type: row\n config:\n style: \"height: 130px; font-size: 23px; color: #233067; font-family: Nanum Gothic; letter-spacing: 1.2px;\"\n elements:\n - type: col\n size: 8\n config:\n style: \"text-align: right; padding-right: 30px;\"\n elements:\n - type: row\n elements:\n - type: col\n elements:\n - type: content\n label: passport\n - type: col\n size: 4\n - type: row\n config:\n style: \"margin-top: 20px;\"\n elements:\n - type: col\n size: 3\n - type: col\n size: 7\n config:\n style: \"padding-left: 4px; padding-right: 0;\"\n elements:\n - type: attribute\n name: photoImage\n part: data\n config:\n style: \"height: 281px; width: 203px;\"\n - type: col\n size: 8\n config:\n style: \"padding-left: 0; margin-left: -1px;\"\n elements:\n - type: row\n config:\n style: \"font-size: 23px; color: #233067; font-family: 'Nanum Gothic'; letter-spacing: 1.2px;\"\n elements:\n - type: attribute\n name: issuingState\n part: data\n config:\n style: \"letter-spacing: 0.2px;\"\n - type: row\n config:\n style: \"margin-top: 16px; font-size: 11px; color: #233067; font-family: 'Nanum Gothic';\"\n elements:\n - type: col\n size: 3\n config:\n style: \"padding-left: 0; font-size: 11px;\"\n elements:\n - type: content\n text: Type\n - type: attribute\n name: documentType\n part: code\n config:\n style: \"font-size: 21px; color: #222222; font-family: Euphemia; text-transform: uppercase;\"\n - type: col\n size: 3\n config:\n style: \"padding: 0; margin-left: -20px;\"\n elements:\n - type: content\n text: Code\n - type: attribute\n name: issuingStateCode\n part: code\n config:\n style: \"font-size: 21px; color: #222222; font-family: Euphemia; text-transform: uppercase;\"\n - type: col\n size: 6\n config:\n style: \"padding: 0;\"\n elements:\n - type: row\n elements:\n - type: content\n text: Pass Passeport\n config:\n style: \"padding-left: 13px; letter-spacing: 0.3px;\"\n - type: row\n elements:\n - type: content\n text: Passaporto Passaport Passport No N° Nr\n config:\n style: \"padding-left: 13px; letter-spacing: 0.3px;\"\n - type: attribute\n name: documentNumber\n part: data\n config:\n style: \"font-size: 21px; color: #222222; font-family: Euphemia; text-transform: uppercase;\"\n - type: row\n config:\n style: \"margin-top: -6px; font-size: 10.5px; color: #233067; font-family: 'Nanum Gothic';\"\n elements:\n - type: col\n config:\n style: \"padding-left: 0; letter-spacing: 0.2px;\"\n elements:\n - type: content\n text: 1 Name Nom\n - type: content\n text: Cognome Num Surname\n - type: attribute\n name: primaryIdentifier\n part: data\n config:\n style: \"font-size: 19px; color: #222222; font-family: Euphemia; margin-top: -1px; margin-bottom: 1px;\"\n - type: row\n config:\n style: \"margin-top: 0px; font-size: 10.5px; color: #233067; font-family: 'Nanum Gothic';\"\n elements:\n - type: col\n config:\n style: \"padding-left: 0; letter-spacing: 0.2px;\"\n elements:\n - type: content\n text: 2 Vorname(n) Prenom(s)\n - type: content\n text: Nome(i) Num(s) Given name(s)\n - type: attribute\n name: secondaryIdentifier\n part: data\n config:\n style: \"font-size: 19px; color: #222222; font-family: Euphemia; margin-top: -2px; margin-bottom: 2px;\"\n - type: row\n config:\n style: \"margin-top: 0px; font-size: 11px; color: #233067; font-family: 'Nanum Gothic';\"\n elements:\n - type: col\n config:\n style: \"padding-left: 0; letter-spacing: 0.25px;\"\n elements:\n - type: content\n text: 3 Nationalitat Nationalite\n - type: content\n text: Cittadinanza Naziunalitad Nationality\n - type: attribute\n name: nationality\n part: data\n config:\n style: \"font-size: 19px; color: #222222; font-family: Euphemia; margin-top: -2px; margin-bottom: 2px;\"\n - type: row\n config:\n style: \"margin-top: 0px; font-size: 10px; letter-spacing: 0.65px; color: #233067; font-family: 'Nanum Gothic';\"\n elements:\n - type: col\n size: 5\n config:\n style: \"padding-left: 0;\"\n elements:\n - type: content\n text: 4 Geburtsdatum Date de naissance\n - type: content\n text: Data di nascita Data da naschientscha Date of birth\n - type: attribute\n name: dateOfBirth\n part: data\n config:\n style: \"font-size: 19px; color: #222222; font-family: Euphemia; margin-top: -2px; margin-bottom: 2px;\"\n - type: col\n size: 3\n config:\n style: \"padding-left: 35px;\"\n elements:\n - type: content\n text: 5 Geschlecht Sexe\n - type: content\n text: Sesso Schlattaina Sex\n - type: attribute\n name: sex\n part: code\n config:\n style: \"font-size: 21px; color: #222222; font-family: Euphemia; margin-top: -2px; margin-bottom: 2px;\"\n - type: col\n size: 4\n config:\n style: \"padding-left: 5px;\"\n elements:\n - type: content\n text: 6 Grosse Taille\n - type: content\n text: Statura Grondezza Height\n - type: attribute\n name: optionalPersonalData\n part: data\n config:\n style: \"display: inline-block; font-size: 21px; color: #222222; font-family: Euphemia; margin-top: -2px; margin-bottom: 2px;\"\n - type: content\n text: cm\n config:\n style: \"display: inline-block; font-size: 21px; color: #222222; font-family: Euphemia; margin-top: -2px; margin-bottom: 2px; padding-left: 10px;\"\n - type: row\n config:\n style: \"margin-top: -2px; font-size: 10px; letter-spacing: 0.65px; color: #233067; font-family: 'Nanum Gothic';\"\n elements:\n - type: col\n config:\n style: \"padding-left: 0;\"\n elements:\n - type: content\n text: 7 Heimatort Lieu d'origine\n - type: content\n text: Luogo di attinenza Lieu d'origin Place of origin\n - type: attribute\n name: placeOfBirth\n part: data\n config:\n style: \"font-size: 19px; color: #222222; font-family: Euphemia;\"\n - type: row\n config:\n style: \"margin-top: 2px; font-size: 10px; letter-spacing: 0.65px; color: #233067; font-family: 'Nanum Gothic';\"\n elements:\n - type: col\n size: 5\n config:\n style: \"padding-left: 0;\"\n elements:\n - type: content\n text: 8 Ausgestellt am Delivre le\n - type: content\n text: Rilascuato il Emess ils Date of issue\n - type: attribute\n name: dateOfIssue\n part: data\n config:\n style: \"font-size: 19px; color: #222222; font-family: Euphemia;\"\n - type: col\n size: 7\n config:\n style: \"padding-left: 35px;\"\n elements:\n - type: content\n text: 9 Behorde Autorite\n - type: content\n text: Autorita Autoritad Authority\n - type: attribute\n name: issuedBy\n part: data\n config:\n style: \"font-size: 21px; color: #222222; font-family: Euphemia;\"\n - type: row\n config:\n style: \"margin-top: -1px; font-size: 10px; letter-spacing: 0.65px; color: #233067; font-family: 'Nanum Gothic';\"\n elements:\n - type: col\n config:\n style: \"padding-left: 0;\"\n elements:\n - type: content\n text: 10 Gultig bis Date d'expiration\n - type: content\n text: Data di scadenza Data da scadenza Date of expiry\n - type: attribute\n name: dateOfExpiry\n part: data\n config:\n style: \"font-size: 19px; color: #222222; font-family: Euphemia; margin-top: -2px; margin-bottom: 2px;\"\n - type: row\n config:\n style: \"height: 50px;\"\n elements:\n - type: row\n config:\n style: \"margin-top: 45px; font-family: 'OCRB 10 Pitch BT'; font-size: 31px;\"\n elements:\n - type: col\n elements:\n - type: row\n config:\n style: \"padding-left: 50px; font-size: 31px; letter-spacing: 1.84px;\"\n elements:\n - type: col\n config:\n style: \"white-space: nowrap; overflow: hidden; max-width: 895px;\"\n elements:\n - type: content\n text: P<\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: attribute\n name: issuingStateCode\n part: code\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: attribute\n name: secondaryIdentifier\n part: data\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: content\n text: <<\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: attribute\n name: primaryIdentifier\n part: data\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: content\n text: <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: row\n config:\n style: \"margin-top: 10px; padding-left: 45px; font-size: 30px; letter-spacing: 1.77px;\"\n elements:\n - type: col\n elements:\n - type: attribute\n name: documentNumber\n part: data\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: content\n text: <0\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: attribute\n name: issuingStateCode\n part: code\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: content\n text: \"0000000\"\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: attribute\n name: sex\n part: code\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - type: content\n text: 0000000<<<<<<<<<<<<<<<<0\n config:\n style: \"display: inline-block; text-transform: uppercase;\"\n - config:\n style: \"width: 980px; height: 700px; margin: 0;\"\n background_image: SAI:zQmQQgMSzaL8LkkxSR9FsZYBsU4ouoMXxNTXF6uuAtZEPkg\n name: Page 1\n elements:\n - type: row\n config:\n style: \"height: 160px;\"\n elements:\n - type: row\n elements:\n - type: col\n size: 4\n - type: col\n size: 4\n config:\n style: \"display: flex; justify-content: center;\"\n elements:\n - type: attribute\n name: signatureImage\n part: data\n - type: col\n size: 4\nlabels:\n passport:\n en: Passport\n fr: Passeport\n" -} - - -``` -Code snippet for a Credential Layout Overlay - - -### Form Layout Overlay - -A Form Layout Overlay defines presentation information required by an -application to display a digital form. - - -```json - -{ - "capture_base": "EPMaG1h2hVxKCZ5_3KoNNwgAyd4Eq8zrxK3xgaaRsz2M", - "type": "spec/overlays/form_layout/1.0", - "layout": "rows:\n - config:\n style: 'justify-content: space-between;'\n elements:\n - type: meta\n name: language\n - type: meta\n name: name\n - elements:\n - type: meta\n name: description\n - config:\n style: 'border-style: dashed;'\n elements:\n - type: category\n name: _cat-1_\n - elements:\n - type: attribute\n name: documentType\n part: input\n - type: attribute\n name: issuingStateCode\n part: input\n - type: attribute\n name: documentNumber\n part: input\n - config:\n style: 'border-style: dashed;'\n elements:\n - type: category\n name: _cat-2_\n - elements:\n - type: attribute\n name: primaryIdentifier\n part: input\n - type: attribute\n name: secondaryIdentifier\n part: input\n - type: attribute\n name: nationality\n part: input\n - type: attribute\n name: dateOfBirth\n part: input\n - type: attribute\n name: placeOfBirth\n part: input\n - type: attribute\n name: sex\n part: input\n - type: attribute\n name: optionalPersonalData\n part: input\n - config:\n style: 'border-style: dashed;'\n elements:\n - type: category\n name: _cat-3_\n - elements:\n - type: attribute\n name: dateOfIssue\n part: input\n - type: attribute\n name: issuedBy\n part: input\n - config:\n style: 'border-style: dashed;'\n elements:\n - type: category\n name: _cat-4_\n - elements:\n - type: attribute\n name: signatureImage\n part: input\n - config:\n style: 'border-style: dashed;'\n elements:\n - type: category\n name: _cat-5_\n - elements:\n - type: attribute\n name: photoImage\n part: input\n" -} - -``` -Code snippet for a Form Layout Overlay - - -### Sensitive Overlay -  -A Sensitive Overlay defines attributes not necessarily flagged in the Capture -Base that need protecting against unwarranted disclosure. For example, data that -requires protection for legal or ethical reasons, personal privacy, or -proprietary considerations. - - -```json -TODO -``` From 90bd1dc3705cfa710cfec0f425ead7688cf46961 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Fri, 17 Jan 2025 10:24:28 +0100 Subject: [PATCH 02/46] chore: Archive 1.0.1 version --- docs/specification/README.md | 16 +- docs/specification/v1.0.1.md | 1359 ++++++++++++++++++++++++++++++++++ 2 files changed, 1370 insertions(+), 5 deletions(-) create mode 100644 docs/specification/v1.0.1.md diff --git a/docs/specification/README.md b/docs/specification/README.md index fcb2b04..8a2ed56 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -7,15 +7,21 @@ description: Official OCA specification
-Latest published version: + Version:
-
+
v1.0.2
+
Latest published version:
+
-[https://oca.colossi.network/specification/](https://oca.colossi.network/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.pdf)) + [https://oca.colossi.network/specification/](https://oca.colossi.network/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.pdf)) +
+
Previous version:
+
-
+ [https://oca.colossi.network/specification/v1.0.1/](https://oca.colossi.network/specification/v1.0.1) +
-Author: + Author:
diff --git a/docs/specification/v1.0.1.md b/docs/specification/v1.0.1.md new file mode 100644 index 0000000..1a353a5 --- /dev/null +++ b/docs/specification/v1.0.1.md @@ -0,0 +1,1359 @@ +--- +sidebarDepth: 5 +description: Official OCA specification +--- + +# OCA Technical Specification + +
+
+ Version: +
+
+ v1.0.1 (This version is outdated!) +
+
+ Latest published version: +
+
+ +[https://oca.colossi.network/specification/](https://oca.colossi.network/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.pdf)) + +
+
+Author: +
+
+ +Paul Knowles ([ Human Colossus Foundation ](https://humancolossus.foundation/)) + +
+
+Editors: +
+
+ +Ryan Barrett (Stratosoft LLC) + +Robert Mitwicki ([ Human Colossus Foundation ](https://humancolossus.foundation/)) + +Michal Pietrus ([ ArgonAUTHs ](https://argonauths.eu/)) + +Marcin Olichwiruk ([ ArgonAUTHs ](https://argonauths.eu/)) + +Philippe Page ([ Human Colossus Foundation ](https://humancolossus.foundation/)) + +
+
+Copyrights: +
+
+Human Colossus Foundation, EUPL v1.2 licence. +
+
+Governance: +
+
+ +The Decentralised Semantics Working Group maintains the OCA specification at [ Human Colossus Foundation ](https://humancolossus.foundation). Comments regarding this specification can be provided as issues on the official [ OCA Github ](https://github.com/the-human-colossus-foundation/oca-spec/issues). + +
+
+Contact: +
+
+ +[ contact@humancolossus.org ](mailto:contact@humancolossus.org) + +
+
+ +::: warning Disclaimer +Strictly following DDE Principle 1.4 \[[HCF2022](#ref-HCF2022)\], OCA schema objects MUST be resolvable solely upon the encoded cryptographic digest of their content to ensure objectual integrity. + +All code snippets in this version of the document are in JavaScript Object Notation (JSON) \[[ISO21778](#ref-ISO21778)\] format. However, any serialisation format applies as long as all OCA objects have proper semantics. +::: + +## Introduction + +_This section is non-normative._ + +### How does OCA work? + +OCA is based on the FAIR data principles \[[FAIR2016](#ref-FAIR2016)\], a set of guiding principles to make data findable, accessible, interoperable, and reusable, to enable scientific data management and stewardship, and to be relevant to all digital economy stakeholders. + +OCA represents transient objects (domain-agnostic) and persistent schemas (domain-specific) as multi-dimensional objects consisting of a stable capture base and interoperable overlays. By introducing overlays as linked task-specific objects within the schema stack, the architecture offers an optimal level of efficiency and interoperability in alignment with FAIR principles. + +#### What is a Capture Base? + +A Capture Base is the purest and simplest form of a schema, defining the structural characteristics of a dataset. It is the foundational layer upon which to bind task-specific objects to enhance the meaning of inputted data. + +#### What are Overlays? + +Overlays are task-specific objects that provide cryptographically-bound layers of definitional or contextual metadata to a Capture Base. Any actor interacting with a published Capture Base can use Overlays to transform how inputted data and metadata are displayed to a viewer or guide an agent in applying a custom process to captured data. + +## OCA object types + +An OCA object is either a Capture Base or a task-specific Overlay with a deterministic relationship to a Capture Base. When amalgamated as a Bundle, OCA objects provide the necessary structural, definitional, and contextual information to determine the meaning of inputted data at the time of data capture. + +### Capture Base + +A Capture Base is a stable base object that defines a single dataset in its purest form, providing a structural base to harmonise data. The object defines attribute names and types. It also contains a flagging block that allows schema issuers to mark potentially dangerous attributes that may capture identifying information about entities (i.e., personally identifiable information (PII) or quasi-identifiable information (QII)). Once flagged, all corresponding data can be treated as high-risk throughout the data lifecycle and encrypted or removed at any stage, reducing the risk of re-identification attacks against blinded datasets. + +The Capture Base consists of the following attributes: + +- [ Type ](#type) +- [ Classification ](#classification) +- [ Attributes ](#attributes) +- [ Flagged attributes ](#flagged-attributes) + +```json +{ + "type": "spec/capture_base/1.0", + "classification": "GICS:45102010", + "attributes": { + "dateOfBirth": "DateTime", + "documentNumber": "Text", + "documentType": "Array[Text]", + "fullName": "Text", + "height": "Numeric", + "issuingState": "Text", + "photoImage": "Binary", + "sex": "Text" + }, + "flagged_attributes": [ + "documentNumber", + "fullName", + "dateOfBirth", + "photoImage" + ] +} +``` + +_Example 1. Code snippet for a Capture Base._ + +#### Type + +The `type` attribute identifies the schema object type. + +```abnf +type = "spec/capture_base/" sem_ver +sem_ver = DIGIT "." DIGIT +``` + +_Listing: ABNF core rules \[[RFC5234](#ref-RFC5234)\]_ + +#### Classification + +The "classification" attribute is for capturing a standardised classification scheme and taxonomy code to identify the primary sector, area, or topic of a published schema's intended use. Taxonomy codes provide a means for classifying schemas into groupings according to similar functions, markets, products, or services, ultimately leading to better search results for users interested in different categories. + +Note: All classification schemes are supported. RECOMMENDED schemes include the Global Industry Classification Standard (GICS) \[[GICS](#ref-GICS)\] for industry sector classification and the Sustainable Development Goals (SDGs) \[[UNSDG](#ref-UNSDG)\] for the categorisation of humanitarian advocacy and outreach activities. + +```abnf +classification = taxonomy ":" identifier +taxonomy = 1*( ALPHA / DIGIT / "-" ) +identifier = 1*( ALPHA / DIGIT / "-" / "." ) +``` + +_Listing: ABNF core rules_ + +::: tip Example +For the GICS classification: `"classification": "GICS:10101010"` + +For the SDG classification: `"classification": "SDG:1.1"` +::: + +#### Attributes + +The "attributes" attribute maps key-value pairs where the key is the attribute name and the value is the attribute type. + +##### Attribute name + +An attribute name is a string that uniquely identifies an attribute within an OCA layer and is used to reference that attribute by other layers throughout the OCA bundle. + +##### Attribute type + +An attribute type determines the attribute's syntax and how attributes of that type are compared and sorted. A Capture Base recognises seven core data types: + +- **Text**: a data type that defines a human-readable sequence of characters and the words they form, subsequently encoded into computer-readable formats such as ASCII \[[RFC0020](#ref-RFC0020)\]. +- **Numeric**: a data type that defines anything relating to or containing numbers. Examples of numeric data types include 8-byte integers, fixed precision and scale numeric data, floating precision number data, integer (whole number) data, and monetary data values. +- **Reference**: a data type that defines a Self-Addressing IDentifier (SAID) \[[SAID](#ref-SAID)\] that references a set of attributes through its associated parent. For example, the reference data type enables the development of nested data objects, where the organisation of information is in layers or where objects contain other similar objects. SAID is an identifier that is deterministically generated from and embedded in the content it identifies, making it and its data mutually tamper-evident. +- **Boolean**: a data type where the data only has two possible variables: true or false. In computer science, Boolean is an identification classifier for calculating logical truth values and algebraic variables. +- **Binary**: a data type that defines a binary code signal, a series of electrical pulses representing numbers, characters, and performed operations. Based on a binary number system, each digit position represents a power of two (e.g., 4, 8, 16, etc.). A set of four binary digits or bits in binary code represents each decimal number (0 to 9). Each digit has two possible states: off and on (usually symbolised by 0 and 1). Combining basic Boolean algebraic operations on binary numbers makes it possible to represent each of the four fundamental arithmetic operations of addition, subtraction, multiplication, and division. +- **DateTime**: a data type that defines the number of seconds or clock ticks that have elapsed since the defined epoch for that computer or platform. Common formats include dates (e.g., YYYY-MM-DD), times (e.g., hh:mm:ss), dates and times concatenated (e.g., `YYYY-MM-DDThh:mm:ss.sss+zz:zz`), and durations (e.g., `PnYnMnD`). + + Note: The ISO 8601 \[[ISO8601](#ref-ISO8601)\] date and time format is the RECOMMENDED representation format for the dateTime data type, in which the Unix epoch is `1970-01-01T00:00:00Z`. + + :::tip For the Unix epoch example: + Data type: `DateTime`
+ Character encoding: `UTF-8` (default)
+ Standard: `ISO 8601`
+ Format: `YYYY-MM-DDThh:mm:ssZ` + ::: + +- **Array[data type]**: a data type that defines a structure that holds several data items or elements of the same data type. When you want to store many pieces of data that are related and have the same data type, it is often better to use an array instead of many separate variables (e.g., `Array[Text]`, `Array[Numeric]`, etc.). + +#### Flagged attributes + +Any attributes defined in a Capture Base that may contain identifying information about entities (i.e., personally identifiable information (PII) or quasi-identifiable information (QII)) can be flagged. + +The Blinding Identity Taxonomy (BIT) \[[KAN2020](#ref-KAN2020)\] is a practical tool for any practitioner whose organisation has custody or control of a dataset containing identifiable information about entities, including a natural person, organisation, or device with signing capabilities that make that entity uniquely identifiable. For example, data protection officers and schema issuers can use the BIT to flag a list of elements which require cryptographic encoding to reduce the risk of identifying a data principal. + +### Overlays + +Overlays are cryptographically-linked objects that provide layers of task-oriented definitional or contextual information to a Capture Base. Any actor interacting with a published Capture Base can use Overlays to add metadata to the underlying object, transform how information is displayed to a viewer, or guide an agent in applying a custom process to captured data. + +Overlays consist of the following attributes: + +- [ Capture base ](#capture-base-1) +- [ Type ](#type-1) +- Overlay-specific attributes + - See specific overlay types for more information. + +#### Common attributes + +##### Capture base + +The `capture_base` attribute contains the SAID of the Capture Base to cryptographically anchor to that parent object. + +##### Type + +The `type` attribute identifies the schema object type. + +```abnf +type = "spec/overlay/" overlay_name "/" sem_ver +overlay_name = ALPHA +sem_ver = DIGIT "." DIGIT +``` + +_Listing: ABNF core rules_ + +##### Language + +The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has standardised two lists of language-related codes: the language codes called ISO 639-1 alpha-2 \[[ISO639](#ref-ISO639)\] codes ("Codes for the representation of names of languages") and ISO 3166-1 alpha-2 \[[ISO3166](#ref-ISO3166)\] codes ("Codes for the representation of names of countries"). Both consist of two letters. The language code is written in lowercase while the country code is written in uppercase. However, both ISO classifications may be combined to differentiate regional languages. + +The `language` attribute MUST contain either the two-letter language code (lowercase) for a national language or the combined language (lowercase)/country (uppercase) code for a regional language or locale. + +![Table 1](/images/spec-table1.png) +_Table 1. An example of ISO standard values for language and combined language/country codes._ + +#### Semantic Overlays + +Semantic overlays provide contextual meaning to describe objects and their relationships. + +![Fig 1](/images/spec-fig1.png) +_Figure 1. In a balanced network, semantic overlays determine the meaning and use of what is put in, taken in, or operated on by any process or system._ + +##### Character Encoding Overlay + +A Character Encoding Overlay defines the process of assigning numbers to graphical characters, especially the written characters of human language, allowing them to be stored, transmitted, and transformed using digital computers. Character encoding using internationally accepted standards permits worldwide interchange of text in electronic form. + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Character Encoding Overlay MAY include the following attributes: + +- `default_character_encoding` + + The "default_character_encoding" attribute specifies the default character encoding for the attributes contained in the parent Capture Base. + + The most common default character set is UTF-8 \[[RFC3629](#ref-RFC3629)\], which accounts for 98% of all web pages in the World Wide Web and up to 100.0% for some languages, as of 2021. + +- `attr_character_encoding` + + The `attr_character_encoding` attribute maps key-value pairs where the key is the attribute name and the value is the character encoding. + + Any attributes contained in the `attr_character_encoding` attribute override the behaviour of the `default_character_encoding` attribute. + + There are many encoding standards including Base64 \[[RFC4648](#ref-RFC4648)\], UTF-8, and ASCII to name a few. Each standard has a purpose, and applications using those encoding standards expect to receive data compliant with that encoding standard. The most popular types of character encoding are ASCII and Unicode \[[UNICODE](#ref-UNICODE)\]. While ASCII is still supported by nearly all text editors, Unicode is more commonly used because it supports a larger character set. Unicode is often defined as UTF-8, UTF-16 \[[RFC2781](#ref-RFC2781)\], or UTF-32 \[[ISO10646](#ref-ISO10646)\], which refer to different Unicode standards. + + :::tip An example of character encoding for a text format: + Data type: `Text`
+ Character encoding: `UTF-8` (default)
+ Standard: `ReGex`
+ Format: `[A-Z0-9]{9}` + ::: + + :::tip An example of binary-to-text encoding for an image format: + Data type: `Binary`
+ Character encoding: `Base64`
+ Standard: `ISO/IEC 10918`
+ Format: `image/jpeg` + ::: + + ```json + { + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/character_encoding/1.0", + "default_character_encoding": "utf-8", + "attribute_character_encoding": { + "photoImage": "base64" + } + } + ``` + + _Example 2. Code snippet for a Character Encoding Overlay._ + +##### Format Overlay + +A Format Overlay defines an input and display format for data fields. The data format enables conversion of the input buffer to the program variable and displays program variable data to form fields. + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Format Overlay MUST include the following attribute: + +- `attribute_formats` + + The "attribute_formats" attribute maps key-value pairs where the key is the attribute name and the value is the format. + +The inputted format values are dependent on the following core data types as defined by the attribute types in the Capture Base: + +- **Text**: The inputted format value for this core data type MAY be a regular expression [REGEX], a sequence of characters that specifies a search pattern in text. + +- **Binary**: The inputted format value for this core data type MAY be a MIME type registered with the Internet Assigned Numbers Authority (IANA) \[[IANA](#ref-IANA)\] + +- **DateTime**: The inputted format value for this core data type MAY be a date and time representation as defined by ISO 8601, a standard for the worldwide exchange and communication of date and time-related data. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/format/1.0", + "attribute_formats": { + "dateOfBirth": "YYYY-MM-DD", + "documentNumber": "[A-Z0-9]{9}", + "photoImage": "image/jpeg", + "sex": "[A-Z]{1}" + } +} +``` + +_Example 3. Code snippet for a Format Overlay._ + +##### Information Overlay + +_[language-specific object]_ + +An Information Overlay defines attribute field descriptions and usage notes to assist the data entry process or to add context to presented data. + +In addition to the `capture_base`, `type`, and `language` attributes (see [Common attributes](#common-attributes)), the Information Overlay MUST include the following attribute: + +- `attribute_information` + + The `attribute_information` attribute maps key-value pairs where the key is the attribute name and the value is the informational prose in a specific language. + +```json +{ + "capture_base":"EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type":"spec/overlays/information/1.0", + "language":"en", + "attribute_information":{ + "dateOfBirth":"Holder’s date of birth as recorded by the issuing State or organization.", + "documentNumber":"Unique identification number of the document.", + "documentType":"The word for "passport" in the language of the issuing State or organization.", + "fullName":"Full name of the passport holder.", + "height":"Recorded height of the passport holder.", + "issuingState":"Name of the State or organization responsible for issuing the passport.", + "photoImage":"Portrait image of the passport holder.", + "sex":"Sex of the passport holder." + } +} +``` + +_Example 4. Code snippet for an Information Overlay (language: en)._ + +##### Label Overlay + +_[language-specific object]_ + +A Label Overlay defines attribute and category labels. For example, for an attribute named `dateOfBirth`, you may wish to display the label as `Date of birth`, which is more meaningful and user-friendly when displayed to an end user in places such as form inputs and error messages. + +In addition to the `capture_base`, `type`, and `language` attributes (see [Common attributes](#common-attributes)), the Label Overlay MUST include the following attribute: + +- `attribute_labels` + + The `attribute_labels` attribute maps key-value pairs where the key is the attribute name and the value is a human-meaningful attribute label in a specific language. + +and MAY include the following attributes: + +- `attribute_categories` + + The `attribute_categories` attribute contains category identifiers. + +- `category_labels ` + + The `attribute_categories` attribute maps key-value pairs where the key is the attribute name and the value is a human-meaningful category label in a specific language. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/label/1.0", + "language": "en", + "attribute_labels": { + "dateOfBirth": "Date of birth", + "documentNumber": "Passport Number", + "documentType": "Document", + "fullName": "Name", + "height": "Height", + "issuingState": "Issuing State or organization (in full)", + "photoImage": "Portrait image", + "sex": "Sex" + }, + "attribute_categories": ["_cat-1_", "_cat-2_", "_cat-3_", "_cat-4_"], + "category_labels": { + "_cat-1_": "Mandatory header", + "_cat-2_": "Mandatory personal data elements", + "_cat-3_": "Mandatory identification feature", + "_cat-4_": "Optional data elements" + } +} +``` + +_Example 5. Code snippet for a Label Overlay (language: en)._ + +##### Meta Overlay + +_[language-specific object]_ + +A Meta Overlay defines any language-specific information about a schema. It is used for discovery and identification and includes elements such as the schema name and description. + +In addition to the `capture_base`, `type`, and `language` attributes (see [Common attributes](#common-attributes)), the Meta Overlay SHOULD include the following attributes: + +- `name` + + The `name` attribute contains the name of the schema in a specific language. + +- `description ` + + The `description` attribute contains a description of the schema in a specific language. + +and MAY include other attributes at the discretion of the overlay producer, such as an "affiliation" attribute in the example below. How the overlay producer conveys the purpose of the additional attributes in the Meta Overlay is outside the scope of this specification. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/meta/1.0", + "language": "en", + "name": "Digital Passport", + "description": "An example of a Digital Passport schema", + "affiliation": "The Government of Antarctica" +} +``` + +_Example 6. Code snippet for a Meta Overlay (language: en)._ + +##### Standard Overlay + +A Standard Overlay defines a documented agreement or technical specification published by a standards organisation used to represent, format, define, structure, tag, transmit, manipulate, use, and manage data. + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Standard Overlay MUST include the following attribute: + +- `attr_standards` + + The `attr_standards` attribute maps key-value pairs where the key is the attribute name and the value is the standard. + +There are many international standards organisations establishing tens of thousands of standards covering almost every conceivable topic. The three largest and most well-established standards organisations are the International Organization for Standardization (ISO), the International Electrotechnical Commission (IEC) \[[IEC](#ref-IEC)\], and the International Telecommunication Union (ITU) \[[ITU](#ref-ITU)\]. Standards tend to contain the acronym of the standards organisation followed by an internal document identifier. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/standard/1.0", + "attr_standards": { + "dateOfBirth": "ISO 8601" + } +} +``` + +_Example 7. Code snippet for a Standard Overlay._ + +#### Inputs Overlays + +Inputs overlays provide predefined inputs for data attestations. + +![Fig 2](/images/spec-fig2.png) +_Figure 2. In a balanced network, inputs overlays determine what is put in, taken in, or operated on by any process or system._ + +##### Cardinality Overlay + +A Cardinality Overlay defines the minimum and maximum number of values that an attribute can have. For a relationship, the cardinality interval specifies the minimum and maximum number of relationship targets. + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Cardinality Overlay MUST include the following attribute: + +- `attr_cardinality` + + The `attr_cardinality` attribute maps key-value pairs where the key is the attribute name and the value is the cardinality interval. + +The logic of cardinality intervals is as follows: + +- `n` : The cardinality interval denotes exactly `n` entries; +- `n-` : The cardinality interval denotes a minimum of `n` entries; +- `n-m` : The cardinality interval denotes a minimum of `n` and maximum of `m` entries; +- `-m` : The cardinality interval denotes a maximum of `m` entries. + +Note that `n` and `m` are positive integers. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/cardinality/1.0", + "attr_cardinality": { + "documentType": "1-2" + } +} +``` + +_Example 8. Code snippet for a Cardinality Overlay._ + +##### Conditional Overlay + +A Conditional Overlay defines conditional expressions (or rules) that trigger specific computations or actions depending on whether, upon evaluation, programmer-defined Boolean expressions return true or false values. Met conditions can have a direct impact on data capture and data validation processes where, for example, expressions: + +- MAY facilitate schema extensions; +- MAY enable schema abstractions; +- MAY activate validation processes. + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Conditional Overlay MUST include the following attributes: + +- `attribute_conditions ` + + The `attribute_conditions` attribute maps key-value pairs where the key is the attribute name and the value is the conditional expression. + + Expressions MAY contain placeholders to be substituted by values defined by the `attribute_dependencies` attribute. + + ```abnf + conditional-statement = 1*conditional-expression + conditional-expression = equality-relational / equality-relational logical-operator + equality-relational = equality-expression / relational-expression + logical-operator = *SP ("and" / "or") *SP + equality-expression = assignment eql-op assignment + eql-op = "=="/ "~=" + relational-expression = assignment relational-op assignment + relational-op = "<" / ">" / "<=" / ">=" + assignment = *SP (ALPHA / DIGIT / "\${" DIGIT "}") *SP + ``` + + _Listing: ABNF core rules_ + +- `attribute_dependencies ` + + The `attribute_dependencies` attribute maps key-value pairs where the key is the attribute name and the value is an array value which triggers the evaluation process of the conditional expression defined by the `attribute_conditions` attribute. + +```json +{ + "capture_base":"EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type":"spec/overlays/conditional/1.0", + "attribute_conditions":{ + "idCardNumber":"${0}=='ID_CARD'", + "passportNumber":"${0}=='PASSPORT'" + }, + "attribute_dependencies":{ + "idCardNumber":[ + "documentType" + ], + "passportNumber":[ + "documentType" + ] + } +} + +// Entry code overlay with options for `documentType` +{ + "capture_base":"EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type":"spec/overlays/entry_code/1.0", + "attribute_entry_codes":{ + "documentType":[ + "ID_CARD", + "PASSPORT" + ] + } +} +``` + +_Example 9. Code snippet for a Conditional Overlay. When the condition matches for `idCardNumber,` that is, `documentType` matches `ID_CARD,` the default behavior is to apply other overlays to `idCardNumber,` i.e., conformance. `${0}` is an integer placeholder that refers to a replacement value during the substitution process. The `attribute_dependencies` attribute provides that replacement value through an array of attributes. Therefore, the placeholder's integer value refers to an array index that points to the value. In other words, `documentType` is bound by the integer placeholder, which triggers the evaluation process of the expression._ + +##### Conformance Overlay + +A Conformance Overlay indicates whether data entry for each attribute is mandatory or optional. + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Conformance Overlay MAY include the following attributes: + +- `attribute_conformance ` + + The `attribute_conformance` attribute maps key-value pairs where the key is the attribute name and the value is the data entry conformance of the attribute, which is set to either `M` (mandatory) or `O` (optional). + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/conformance/1.0", + "attribute_conformance": { + "dateOfBirth": "M", + "documentNumber": "M", + "documentType": "M", + "fullName": "M", + "height": "O", + "issuingState": "M", + "photoImage": "M", + "sex": "M" + } +} +``` + +_Example 10. Code snippet for a Conformance Overlay._ + +##### Entry Code Overlay + +An Entry Code Overlay defines the entry keys in a series of key-value pairs stored in a code table (also known as a "lookup table") or dataset. The key is a unique identifier that points to its associated value. + +![Table 2](/images/spec-table2.png) +_Table 2. An example of how the values in an array of key-value pairs provided by an Entry Code Overlay subsequently define a set of pre-defined entry keys in a nested series of key-value pairs. The specified values are often standardised categorisation codes, valuable data inputs for statistical analysis, machine learning (ML), and artificial intelligence (AI) algorithms._ + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Entry Code Overlay MUST include the following attribute: + +- `attribute_entry_codes ` + + The `attribute_entry_codes` attribute maps key-value pairs where the key is the attribute name and the value is either: + + - a set of pre-defined entry keys for a nested series of key-value pairs; or + + - a SAID that references a code table from an external data source to retrieve an array of pre-defined entry keys for a nested series of key-value pairs. See [Code Tables](#code-tables) for more information on code tables. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/entry_code/1.0", + "attribute_entry_codes": { + "documentType": ["PE", "PM"], + "issuingState": "EGyWgdQR9dW_I5oHlHBMoO9AA_eMeb2p3XzcCRCBbKCM", + "sex": ["F", "M", "X"] + } +} +``` + +_Example 11. Code snippet for an Entry Code Overlay._ + +##### Entry Overlay + +_[language-specific object]_ + +An Entry Overlay defines the entry values in a series of key-value pairs stored in a code table (also known as a "lookup table") or dataset. A value is either the identified data or a pointer to that data. + +![Table 3](/images/spec-table3.png) +_Table 3. An example of how an Entry Overlay can leverage a set of pre-defined entry keys in a nested series of key-value pairs provided by an Entry Code Overlay to provide human-meaningful values in a specified national or regional language._ + +In addition to the `capture_base`, `type`, and `language` attributes (see [Common attributes](#common-attributes)), the Entry Overlay MUST include the following attribute: + +- `attribute_entries` + + The `attribute_entries` attribute maps key-value pairs where the key is the attribute name and the value is either: + + - a set of pre-defined values in a nested series of key-value pairs that are human-meaningful and language-dependent where the entry keys are taken from an associated Entry Code Overlay; or + + - a SAID that references a code table from an external data source to retrieve an array of pre-defined values from a nested series of key-value pairs that are human-meaningful and language-dependent where the entry keys are taken from an associated Entry Code Overlay. See [Code Tables](#code-tables) for more information. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/entry/1.0", + "language": "en", + "attribute_entries": { + "documentType": { + "PE": "DIPLOMATIC PASSPORT", + "PM": "PASSPORT" + }, + "issuingState": "Els6NxGvFfyL5aiBWR3j7YiaS7F4j4O-F0EIlZu-dO0g", + "sex": { + "F": "Female", + "M": "Male", + "X": "Unspecified" + } + } +} +``` + +_Example 12. Code snippet for an Entry Overlay (language: en)._ + +##### Unit Overlay + +A Unit Overlay defines the units of measurement adopted by convention or law, used as a standard for measuring the same kind of quantitative data. The RECOMMENDED system to use is the International System of Units (SI) \[[BIPM](#ref-BIPM)\], French Système International d’Unités, an international decimal system of weights and measures derived from and extending the metric system of units. + +Adopted by the 11th General Conference on Weights and Measures (CGPM) in 1960, it is abbreviated SI in all languages. To date, the SI comprises seven base units: the meter (m), the kilogram (kg), the second (s), the ampere (A), the kelvin (K), the candela (cd) and the mole (mol). + +![Fig 3](/images/spec-fig3.png) + +_Figure 3. The seven defining constants of the SI._ + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Unit Overlay SHOULD include the following attribute: + +- `metric_system` + + The `metric_system` attribute contains the acronym of the chosen system of units (a coherent system of units of measurement) used for defining attribute units. + +and MUST include the following attribute: + +- `attribute_units` + + The `attribute_units` attribute maps key-value pairs where the key is the attribute name and the value is a standard unit of measurement from a known metric system. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/unit/1.0", + "metric_system": "SI", + "attribute_units": { + "height": "cm" + } +} +``` + +_Example 13. Code snippet for a Unit Overlay._ + +#### Transformation Overlays + +Transformation overlays provide information to convert data from one format or structure to another, such as raw data to processed, or unstructured to structured. + +##### Attribute Mapping Overlay + +An Attribute Mapping Overlay defines attribute mappings between two distinct data models. Data mapping provides a preliminary step for data integration tasks, including data transformation or data mediation between a data source and a destination or consolidation of multiple databases into a single database and identifying redundant columns of data for consolidation or elimination. + +```json +{ + "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc", + "type": "spec/overlays/mapping/1.0", + "attribute_mapping": { + "first_name": "firstName", + "last_name": "surname" + } +} +``` + +_Example 14. Code snippet for an Attribute Mapping Overlay._ + +##### Entry Code Mapping Overlay + +An Entry Code Mapping Overlay defines the entry key mappings between two distinct code tables or datasets. + +```json +{ + "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc", + "type": "spec/overlays/entry_code_mapping/1.0", + "attr_entry_codes_mapping": { + "country_code": [ + "AFG:AF", + "ALB:AL", + "DZA:DZ", + "ASM:AS", + "AND:AD", + "AGO:AO", + "AIA:AI", + "ATA:AQ", + "ATG:AG", + "..." + ] + } +} +``` + +_Example 15. Code snippet for an Entry Code Mapping Overlay._ + +##### Subset Overlay + +A Subset Overlay defines a customised version of a published schema containing a subset of source attributes, including their properties, types, codes, and relationship dependencies required for the information exchange. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/subset/1.0", + "attributes": ["dateOfBirth", "documentNumber", "documentType"] +} +``` + +_Example 16. Code snippet for a Subset Overlay._ + +##### Unit Mapping Overlay + +A Unit Mapping Overlay defines target units for quantitative data when converting between different units of measurement. Conversion of units is the conversion between different units of measurement for the same quantity, typically through multiplicative conversion factors (see [Code Table for Unit mappings](#code-table-for-unit-mappings) for more information on conversion factors) which change the measured quantity value without changing its effects. The process of conversion depends on the specific situation and the intended purpose. This may be governed by regulation, contract, technical specifications or other published standards. + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Unit Mapping Overlay MUST include the following attributes: + +- `metric_system` + + The `metric_system` attribute contains the acronym of the chosen system of units (a coherent system of units of measurement) used for defining attribute units. + +- `code_table` + + The `code_table` attribute contains a SAID that references an external code table. See [Code Tables](#code-tables) for more information. + +- `attr_units` + + The `attr_units` attribute maps key-value pairs where the key is the attribute name and the value is the desired unit of measurement. + +```json +{ + "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc", + "type": "spec/overlays/unit/1.0", + "metric_system": "SI", + "code_table": "E3YDLacdI1GSGWhHywzrb5B0hOL/9TYWBsUkXC8fA4EY", + "attr_units": { + "blood_glucose": "mg/dL" + } +} +``` + +_Example 17. Code snippet for a Unit Mapping Overlay._ + +#### Presentation Overlays + +Presentation overlays provide information to display digital documents at the application layer, including digital forms and credentials. + +##### Layout Overlay + +::: danger [Currently under review by Decentralised Semantics Working Group] +::: + +A Layout Overlay defines presentation information required by an application to display a digital document, including a digital form or credential. + +::: warning Disclaimer: +Collaborators in several open communities have shown an interest in leveraging OCA’s "task-specific" ethos to work on new overlay types to ensure that data presentation (see [Presentation](#presentation)) is both extensible and interoperable. Deprecation of the Layout Overlay in favour of a more granular approach is likely in the future. +::: + +##### Sensitive Overlay + +A Sensitive Overlay defines attributes not necessarily flagged in the Capture Base that need protecting against unwarranted disclosure. For example, data that requires protection for legal or ethical reasons, personal privacy, or proprietary considerations. + +In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Sensitive Overlay MUST include the following attribute: + +- `attributes` + + The `attributes` attribute is an array of attributes considered sensitive. + +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/sensitive/1.0", + "attributes": ["sex"] +} +``` + +_Example 19. Code snippet for a Sensitive Overlay_ + +### Bundle + +An OCA Bundle contains a set of OCA objects consisting of a Capture Base and bound Overlays. An encoded cryptographic digest of the contained objects produces a deterministic identifier for the bundle. + +The following object types are REQUIRED in any OCA bundle to preserve the minimum amount of structural, definitional, and contextual information to capture the meaning of inputted data. + +- Capture base +- Character encoding overlay +- Format overlay + +The cardinality of several overlay types, particularly the language-specific ones (Entry, Information, Label, and Meta), can be multiple depending on the number of defined supported languages. + +``` + EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis.json +├── E3SAKe0z83pfBnhhcZl19PGGKBheb35WeCJ3V6RdqwY8.json +├── Ejx0o0yuwp99vi0V-ssP6URZIXRMGj1oNKIZ1BXi4sHU.json +├── EZv1B5nNl4Rty8CXFTALhr8T6qXeO0CcKliM03sdrkRA.json +├── Eri3NLi1fr4QrKoFfTlK31KvWpwrSgGaZ0LLuWYQaZfI.json +├── EY0UZ8aYAPusaWk_TON8c20gHth2tvZs4eWh7XAfXBcY.json +├── E1mqEb4f6eOMgu5zR857WWlMUwGYwPzZgiM6sWRZkQ0M.json +├── ESEMKWoKKIf5qvngKecV-ei8MwcQc_pPWCH1FrTWajAM.json +├── EyzKEWuMs8kspj4r70_Lc8sdppnDx-hb9QqUQywjmDRY.json +├── EIGknekgJFqjgQ8ah2NwL8zNWbFrllvXVLqezgB6U3Yg.json +├── EgBxL29VsxoZso7YFirlMP334ZuC1mkel-lO7TxPxEq8.json +├── ED9PH0ZBaOci-nbnYfPgYZWGQdkyWxA-nW3REmB3vhu0.json +├── ElJEQGfAvfJEuB7JeNIcvmAPO2DIOaKkpkZyvxO-gQoc.json +├── EpW9bQGs0Lk6k5cJikN0Ep-DN6z29fwZIsbVzMBgTlWY.json +├── EIGj0LQKT9-6gCLV2QZVgi4YQZhrUl0-GKbN7sFTCSAI.json +├── EHDwC_Ucuttrsxh2NVptgBnyG4EMbG5D8QsdbeF9G9-M.json +└── meta.json +``` + +_Example 20. A representation of an OCA Bundle as a ZIP file containing a Capture Base (first row), multiple Overlays, and a metafile (meta.json) that provides key-value mappings between the file names and the names of the OCA object types. Apart from the metafile, each file name directly represents the encoded cryptographic digest of the file._ + +See [ Appendix A ](#appendix-a-an-example-of-metafile-content) for more information on the content of a metafile (`meta.json` in the above example). + +If well-structured, the metadata in an OCA bundle can facilitate many ways for users to search for information, present results, and even manipulate and present information objects without compromising their integrity. + +### Code Tables + +A code table is an external dataset structured as either: + +- an array of data; or +- a map of key-value pairs. + +A code table MUST be identifiable, verifiable, and resolvable by a SAID. + +#### Code Table for Keys + +A Code Table for Keys provides an anchor to a reusable dataset for a common purpose, such as a list of country codes. Therefore, this object MAY be a reference target in an Entry Code Overlay. See [Entry Code Overlay](#entry-code-overlay) for more information. + +A Code Table for Keys MUST include the following attribute: + +- `keys` + + The `keys` attribute is an array of pre-defined entry keys for a nested series of key-value pairs. A key is a unique identifier that points to an associated value. + +```json +{ + "keys": ["AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "..."] +} +``` + +_Example 21. Code snippet for a Code Table for Keys, providing an anchor for, in this case, two-character ISO country codes._ + +#### Code Table for Key-Value pairs + +A Code Table for Key-Value pairs provides a mapping of input values to output values. + +A Code Table for Key-Value pairs MUST include the following attribute: + +- `entries` + + The "entries" attribute is a map of key-value pairs, where the key is the input value (the source) and the value is the output value (the product). + +```json +{ + "entries":{ + "AFG":"AF", "ALB":"AL", "DZA":"DZ", "ASM":"AS", "AND":"AD", + "AGO":"AO", "AIA":"AI", "ATA":"AQ", "ATG":"AG", "..." + } +} +``` + +_Example 22. Code snippet for a Code Table for Key-Value pairs, providing a mapping from, in this case, three-character to two-character ISO country codes._ + +#### Code Table for Unit mappings + +A Code Table for Unit mappings provides a mapping of input units to output units for quantitative data. + +The unit conversion process consists of the following steps: + +1. Read source unit. +1. Read target unit. +1. Convert source unit to target unit. + +Conversion between units is defined as follows: + +``` +Target unit = source unit * conversion factor + offset +``` + +Except when converting between temperature units, offset equals 0 in most cases. + +::: tip An example of Celsius to Kelvin conversion: + +1. Given 37 Celsius +2. Expect Kelvin +3. `37 * 1 + 273.15 = 310.15 K` + +::: + +::: tip An example of Celsius to Fahrenheit conversion: + +1. Given 37 Celsius +2. Expect Fahrenheit +3. `37 * 1.8 + 32 = 98.6 F` + +::: + +Implementers MAY find E.J. Roschke’s "Units and Unit Conversions" (2001) \[[ROS2001](#ref-ROS2001)\] a helpful resource for conversion factors. + +A Code Table for Unit mappings MUST include the following attribute: + +- `entries` + + The `entries` attribute is a map of key-value pairs, where the key denotes the conversion from source to target (e.g., `m->mm` or `deg_c->deg_f`) and the value contains the conversion factor and the offset. + + All units and unit prefixes follow the "Data Protocols Lightweight Standards and Patterns for Data" \[[BER2013](#ref-BER2013)\] proposal for describing units associated with numeric quantities. + +```json +{ + "entries": { + "m->mm": { + "cf": 1000 + }, + "m->yd": { + "cf": 1.0936133 + }, + "deg_c->deg_f": { + "cf": 1.8, + "o": 32 + } + } +} +``` + +_Example 23. Code snippet for a Code Table for Unit mappings._ + +Code Table for Unit mappings is in denormalised form, meaning that the conversion between units and unit prefixes is pre-defined for all standard unit conversions for maximum efficiency. + +## Basic concepts + +_This section is non-normative._ + +Characters provide the essential elements required for written language in the physical world. In the digital world, stored sequences of bytes known as "data" represent these elements. However, without a system of interpretation, data has no inherent morphological, definitional, or contextual meaning. This interpretation is provided by "metadata", sets of data that provide meaning to any stored sequence of bytes. + +OCA is a core utility architecture for capturing the metadata necessary to interpret and preserve the meaning of inputted data. In addition, the architecture introduces a comprehensive solution to support data validation, transformation, and presentation requirements throughout a data lifecycle. + +![Fig 4](/images/spec-fig4.png) + +_Figure 4. Universal OCA lifecycle._ + +### Capture + +Data capture is the process of collecting structured and unstructured information electronically and converting it into data readable by a computer. + +Data capture MAY involve Semantic, Inputs, and Presentation Overlays. + +### Validation + +Data validation is the process of checking the integrity, accuracy and structure of data before it is used for a business operation. + +Data validation MAY involve Semantic and Inputs Overlays. + +### Transformation + +Data transformation is the process of converting data from one format to another, typically from the format of a source system into the required format of a destination system. + +Data transformation MUST involve Transformation Overlays. + +### Presentation + +Data presentation is the process of using various graphical formats to visually represent the relationship between two or more data sets so that, based on the results, the reader or verifier can make an informed decision. + +Data presentation MAY involve Semantic, Inputs, and Presentation Overlays. + +## Conventions and Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted when, and only when, they appear in all capitals, as described in RFC 2119 \[[RFC2119](#ref-RFC2119)\]. + +## References + +### Normative References + +
+
+[ISO21778] +
+
+ +ISO/IEC 21778:2017, Information technology — The JSON data interchange syntax (2017) [ https://www.iso.org/standard/71616.html ](https://www.iso.org/standard/71616.html) + +
+
+[SAID] +
+
+ +Smith, S. Self-Addressing IDentifier (SAID) (2022) [ https://datatracker.ietf.org/doc/html/draft-ssmith-said ](https://datatracker.ietf.org/doc/html/draft-ssmith-said) + +
+
+ +### Informative References + +
+
+
+[ISO21778] +
+
+ +ISO/IEC 21778:2017, Information technology — The JSON data interchange syntax (2017) [ https://www.iso.org/standard/71616.html ](https://www.iso.org/standard/71616.html) + +
+ +
+[SAID] +
+
+ +Smith, S. Self-Addressing IDentifier (SAID) (2022) [ https://datatracker.ietf.org/doc/html/draft-ssmith-said ](https://datatracker.ietf.org/doc/html/draft-ssmith-said) + +
+ +
+[BER2013] +
+
+ +Berkeley, A., Pollock, R., Smith, J. Data Protocols Lightweight Standards and Patterns for Data, Version 0.1 (2013) [http://dataprotocols.org/units/](http://dataprotocols.org/units/) + +
+ +
+[BIPM] +
+
+ +Bureau International des Poids et Mesures (BIPM). The International System of Units (SI) [https://www.bipm.org/en/measurement-units](https://www.bipm.org/en/measurement-units) + +
+ +
+[BRU2019] +
+
+ +Brush, K. Digital ecosystem (2019) +[https://www.techtarget.com/searchcio/definition/digital-ecosystem](https://www.techtarget.com/searchcio/definition/digital-ecosystem) + +
+ +
+[FAIR2016] +
+
+ +Wilkinson, M. et al. The FAIR Guiding Principles for scientific data management and stewardship (2016) [ https://www.nature.com/articles/sdata201618](https://www.nature.com/articles/sdata201618) + +
+ +
+[GICS] +
+
+ +MSCI. The Global Industry Classification Standard (GICS®) [https://www.msci.com/our-solutions/indexes/gics](https://www.msci.com/our-solutions/indexes/gics) + +
+ +
+[HCF2022] +
+
+ +Human Colossus Foundation. Principles of a Dynamic Data Economy (DDE), Version 1.0 (2022) [https://static1.squarespace.com/static/5ead4c8660689c348c80958e/t/62f288b25f9c364d7945e6eb/1660061875006/HCF+DDE+Principles+v1.0.0.pdf](https://static1.squarespace.com/static/5ead4c8660689c348c80958e/t/62f288b25f9c364d7945e6eb/1660061875006/HCF+DDE+Principles+v1.0.0.pdf) + +
+ +
+[IANA] +
+
+ +Internet Assigned Numbers Authority (IANA) [https://www.iana.org/](https://www.iana.org/) + +
+ +
+[ICAO] +
+
+ +International Civil Aviation Organization (ICAO) [https://www.icao.int/Pages/default.aspx](https://www.icao.int/Pages/default.aspx) + +
+ +
+[ICAO9303] +
+
+ +Doc 9303, Machine Readable Travel Documents, Eighth Edition - Part 3: Specifications Common to all MRTDs (2021) [https://www.icao.int/publications/Documents/9303_p3_cons_en.pdf](https://www.icao.int/publications/Documents/9303_p3_cons_en.pdf) + +
+ +
+[IEC] +
+
+ +International Electrotechnical Commission (IEC) [https://iec.ch/homepage](https://iec.ch/homepage) + +
+ +
+[ISO] +
+
+ +International Organization for Standardization (ISO) [https://www.iso.org/home.html](https://www.iso.org/home.html) + +
+ +
+[ISO639] +
+
+ +ISO 639-1:2002, Codes for the representation of names of languages — Part 1: Alpha-2 code (2019) [https://www.iso.org/standard/22109.html](https://www.iso.org/standard/22109.html) + +
+ +
+[ISO3166] +
+
+ +ISO 3166-1:2020, Codes for the representation of names of countries and their subdivisions — Part 1: Country code (2020) [https://www.iso.org/standard/72482.html](https://www.iso.org/standard/72482.html) + +
+ +
+[ISO7501] +
+
+ +ISO/IEC 7501-1:2008, Identification cards — Machine readable travel documents — Part 1: Machine-readable passport (2021) [https://www.iso.org/standard/45562.html](https://www.iso.org/standard/45562.html) + +
+ +
+[ISO8601] +
+
+ +ISO 8601:2019, Date and time format (2019) [https://www.iso.org/iso-8601-date-and-time-format.html](https://www.iso.org/iso-8601-date-and-time-format.html) + +
+ +
+[ISO10646] +
+
+ +ISO/IEC 10646:2020, Information technology — Universal coded character set (UCS) (2020) [https://www.iso.org/standard/76835.html](https://www.iso.org/standard/76835.html) + +
+ +
+[ITU] +
+
+ +International Telecommunication Union (ITU) [https://www.itu.int/en/Pages/default.aspx](https://www.itu.int/en/Pages/default.aspx) + +
+ +
+[KAN2020] +
+
+ +Knowles, P., Klingenstein, K., Wunderlich, J. Blinding Identity Taxonomy (BIT), Version 1.0 (2020, Kantara Initiative) [https://docs.kantarainitiative.org/Blinding-Identity-Taxonomy-Report-Version-1.0.pdf](https://docs.kantarainitiative.org/Blinding-Identity-Taxonomy-Report-Version-1.0.pdf) + +
+ +
+[KNO2022] +
+
+ +Knowles, P., Mitwicki, R., Page, P. Decentralised semantics in distributed data ecosystems: Ensuring the structural, definitional, and contextual harmonisation and integrity of deterministic objects and objectual relationships (2022) [http://star.informatik.rwth-aachen.de/Publications/CEUR-WS/Vol-3249/paper4-OSS.pdf](http://star.informatik.rwth-aachen.de/Publications/CEUR-WS/Vol-3249/paper4-OSS.pdf) + +
+ +
+[REGEX] +
+
+ +DOCS.RS, Crate RegEx (Regular Expression), Version 1.6.0 [ https://docs.rs/regex/latest/regex/#syntax](https://docs.rs/regex/latest/regex/#syntax) + +
+ +
+[RFC0020] +
+
+ +Cerf, V. ASCII format for network interchange, STD 80, RFC 20, DOI 10.17487/RFC0020 (October 1969) [https://www.rfc-editor.org/info/rfc20](https://www.rfc-editor.org/info/rfc20) + +
+ +
+[RFC2119] +
+
+ +Bradner, S. Key words for use in RFCs to Indicate Requirement Levels, BCP 14, RFC 2119, DOI 10.17487/RFC2119 (March 1997) [https://www.rfc-editor.org/rfc/rfc2119](https://www.rfc-editor.org/rfc/rfc2119) + +
+ +
+[RFC2781] +
+
+ +Hoffman, P., Yergeau, F. UTF-16, an encoding of ISO 10646, RFC 2781, DOI 10.17487/RFC2781 (February 2000) [ https://www.rfc-editor.org/info/rfc2781](https://www.rfc-editor.org/info/rfc2781) + +
+ +
+[RFC3629] +
+
+ +Yergeau, F. UTF-8, a transformation format of ISO 10646, STD 63, RFC 3629, DOI 10.17487/RFC3629 (November 2003) [https://www.rfc-editor.org/rfc/rfc3629](https://www.rfc-editor.org/rfc/rfc3629) + +
+ +
+[RFC4648] +
+
+ +Josefsson, S. The Base16, Base32, and Base64 Data Encodings, RFC 4648, DOI 10.17487/RFC4648 (October 2006) [https://www.rfc-editor.org/info/rfc4648](https://www.rfc-editor.org/info/rfc4648) + +
+ +
+[RFC5234] +
+
+ +Crocker, D., Ed., Overell, P. Augmented BNF for Syntax Specifications: ABNF, RFC 5234 (January 2008) [https://datatracker.ietf.org/doc/html/rfc5234](https://datatracker.ietf.org/doc/html/rfc5234) + +
+ +
+[UN] +
+
+ +United Nations [https://www.un.org/en/](https://www.un.org/en/) + +
+ +
+[UNICODE] +
+
+ +Unicode [https://home.unicode.org/](https://home.unicode.org/) + +
+ +
+[UNSDG] +
+
+ +United Nations. Sustainable Development Goals (SDGs) [https://sdgs.un.org/goals](https://sdgs.un.org/goals) + +
+
+
+ +## Appendices + +### Appendix A. An example of Metafile content + +```json +{ + "files": { + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] character_encoding": "E3SAKe0z83pfBnhhcZl19PGGKBheb35WeCJ3V6RdqwY8", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] conditional": "Ejx0o0yuwp99vi0V-ssP6URZIXRMGj1oNKIZ1BXi4sHU", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] conformance": "EZv1B5nNl4Rty8CXFTALhr8T6qXeO0CcKliM03sdrkRA", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] entry (en)": "Eri3NLi1fr4QrKoFfTlK31KvWpwrSgGaZ0LLuWYQaZfI", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] entry (fr)": "EY0UZ8aYAPusaWk_TON8c20gHth2tvZs4eWh7XAfXBcY", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] entry_code": "E1mqEb4f6eOMgu5zR857WWlMUwGYwPzZgiM6sWRZkQ0M", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] format": "ESEMKWoKKIf5qvngKecV-ei8MwcQc_pPWCH1FrTWajAM", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] information (en)": "EyzKEWuMs8kspj4r70_Lc8sdppnDx-hb9QqUQywjmDRY", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] information (fr)": "EIGknekgJFqjgQ8ah2NwL8zNWbFrllvXVLqezgB6U3Yg", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] label (en)": "EgBxL29VsxoZso7YFirlMP334ZuC1mkel-lO7TxPxEq8", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] label (fr)": "ED9PH0ZBaOci-nbnYfPgYZWGQdkyWxA-nW3REmB3vhu0", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] layout": "ElJEQGfAvfJEuB7JeNIcvmAPO2DIOaKkpkZyvxO-gQoc", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] meta (en)": "EpW9bQGs0Lk6k5cJikN0Ep-DN6z29fwZIsbVzMBgTlWY", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] meta (fr)": "EIGj0LQKT9-6gCLV2QZVgi4YQZhrUl0-GKbN7sFTCSAI", + "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] unit": "EHDwC_Ucuttrsxh2NVptgBnyG4EMbG5D8QsdbeF9G9-M", + "capture_base-0": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis" + }, + "root": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis" +} +``` From 735d059a3d03dcf16fea13ff9a3ebbea58e9f7e7 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Fri, 17 Jan 2025 17:09:19 +0100 Subject: [PATCH 03/46] docs: Improve OCA bundle normative description --- docs/specification/README.md | 211 ++++++++++++++++++++++++----------- 1 file changed, 147 insertions(+), 64 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 8a2ed56..533b527 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -6,22 +6,22 @@ description: Official OCA specification # OCA Technical Specification
+
+ Version: +
+
+ v1.0.2 +
- Version: + Latest published version:
-
v1.0.2
-
Latest published version:
-
+
- [https://oca.colossi.network/specification/](https://oca.colossi.network/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.pdf)) -
-
Previous version:
-
+[https://oca.colossi.network/specification/](https://oca.colossi.network/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.pdf)) - [https://oca.colossi.network/specification/v1.0.1/](https://oca.colossi.network/specification/v1.0.1) -
+
- Author: +Author:
@@ -832,41 +832,150 @@ _Example 19. Code snippet for a Sensitive Overlay_ ### Bundle -An OCA Bundle contains a set of OCA objects consisting of a Capture Base and bound Overlays. An encoded cryptographic digest of the contained objects produces a deterministic identifier for the bundle. +An OCA Bundle is a set of OCA objects which MUST included a `Capture Base` and MAY consist of any number of `Overlays`. An encoded cryptographic digest of the contained objects produces a +deterministic identifier for the bundle. + +#### Canonical form + +OCA Bundles MUST be serializable to be transferred over the network. The +serialization algorithm MUST be deterministic and operate on the canonical form +of the Bundle, which ensures proper ordering of the attributes within OCA +Objects. The serialization algorithm consists of the following rules: + +- MUST consist of following attributes in this order: `v`, `d`, `capture_base`, `overlays` + - `v` - version string defined per section [Bundle Version](#bundle-version) + - `d` - deterministic identifier of the bundle + - `capture_base` - the `Capture Base` object defined as per section [Capture Base](#capture-base) + - `overlays` - an array, containing all the overlays, sorted ASC by the `d` attribute + +##### Bundle Version + +To ensure proper versioning and identification of bundles within the OCA +Specification, we define a standardized string format for the bundle version. +This format encodes critical metadata about the bundle, allowing for consistent +interpretation and management across implementations. + +*Bundle Version String Format* -The following object types are REQUIRED in any OCA bundle to preserve the minimum amount of structural, definitional, and contextual information to capture the meaning of inputted data. +The bundle version string must adhere to the following format: -- Capture base -- Character encoding overlay -- Format overlay +``` +OCAS_ +``` + +Where: + +- `OCAS`: A fixed prefix indicating "OCA Structure". This identifies the string as conforming to the OCA Specification's versioning scheme. +- ``: A single-digit integer (0-9) representing the major version of the specification. A change in the major version indicates backward-incompatible updates to the structure. +- ``: A single-digit integer (0-9) representing the minor version of the specification. A change in the minor version indicates backward-compatible updates. +- ``: A string denoting the serialization format of the bundle. Supported format is: `JSON`: JavaScript Object Notation +- ``: A six-digit, zero-padded integer representing the size of the object in hex notation, size of the object is calculated with `d` field with dummy characters the same lenght as the eventual derived value. The dummy character is #, that is, ASCII 35 decimal (23 hex). +- '_': A version string terminator. -The cardinality of several overlay types, particularly the language-specific ones (Entry, Information, Label, and Meta), can be multiple depending on the number of defined supported languages. +*Example*: +A valid bundle version string: ``` - EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis.json -├── E3SAKe0z83pfBnhhcZl19PGGKBheb35WeCJ3V6RdqwY8.json -├── Ejx0o0yuwp99vi0V-ssP6URZIXRMGj1oNKIZ1BXi4sHU.json -├── EZv1B5nNl4Rty8CXFTALhr8T6qXeO0CcKliM03sdrkRA.json -├── Eri3NLi1fr4QrKoFfTlK31KvWpwrSgGaZ0LLuWYQaZfI.json -├── EY0UZ8aYAPusaWk_TON8c20gHth2tvZs4eWh7XAfXBcY.json -├── E1mqEb4f6eOMgu5zR857WWlMUwGYwPzZgiM6sWRZkQ0M.json -├── ESEMKWoKKIf5qvngKecV-ei8MwcQc_pPWCH1FrTWajAM.json -├── EyzKEWuMs8kspj4r70_Lc8sdppnDx-hb9QqUQywjmDRY.json -├── EIGknekgJFqjgQ8ah2NwL8zNWbFrllvXVLqezgB6U3Yg.json -├── EgBxL29VsxoZso7YFirlMP334ZuC1mkel-lO7TxPxEq8.json -├── ED9PH0ZBaOci-nbnYfPgYZWGQdkyWxA-nW3REmB3vhu0.json -├── ElJEQGfAvfJEuB7JeNIcvmAPO2DIOaKkpkZyvxO-gQoc.json -├── EpW9bQGs0Lk6k5cJikN0Ep-DN6z29fwZIsbVzMBgTlWY.json -├── EIGj0LQKT9-6gCLV2QZVgi4YQZhrUl0-GKbN7sFTCSAI.json -├── EHDwC_Ucuttrsxh2NVptgBnyG4EMbG5D8QsdbeF9G9-M.json -└── meta.json +OCAS11JSON000646_ ``` -_Example 20. A representation of an OCA Bundle as a ZIP file containing a Capture Base (first row), multiple Overlays, and a metafile (meta.json) that provides key-value mappings between the file names and the names of the OCA object types. Apart from the metafile, each file name directly represents the encoded cryptographic digest of the file._ +This indicates: +- `OCAS` it is a OCA Bundle. +- The major version is 1. +- The minor version is 1. +- The serialization format is JSON. +- The object size in base64 encoding is 646 bytes. -See [ Appendix A ](#appendix-a-an-example-of-metafile-content) for more information on the content of a metafile (`meta.json` in the above example). +*Validation* + +Consumers of the OCA Specification must implement validation logic to ensure the bundle version string: +- Matches the defined format and structure. +- Uses only supported serialization formats. +- Accurately represents the object's size in base64 encoding. + +Validation failure must result in the rejection of the bundle as non-compliant with the specification. + +*Example*: +TODO update example +``` +{ + "bundle": { + "v": "OCAS11JSON000646_", + "d": "EKHBds6myKVIsQuT7Zr23M8Xk_gwq-2SaDRUprvqOXxa", + "capture_base": { + "d": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", + "type": "spec/capture_base/1.0", + "attributes": { + "d": "Text", + "i": "Text", + "passed": "Boolean" + }, + "classification": "", + }, + "overlays": { + "character_encoding": { + "d": "ED6Eio9KG2jHdFg3gXQpc0PX2xEI7aHnGDOpjU6VBfjs", + "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", + "type": "spec/overlays/character_encoding/1.0", + "attribute_character_encoding": { + "d": "utf-8", + "i": "utf-8", + "passed": "utf-8" + } + }, + "conformance": { + "d": "EJSRe8DnLonKf6GVT_bC1QHoY0lQOG6-ldqxu7pqVCU8", + "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", + "type": "spec/overlays/conformance/1.0", + "attribute_conformance": { + "d": "M", + "i": "M", + "passed": "M" + } + }, + "information": [ + { + "d": "EIBXpVvka3_4lheeajtitiafIP78Ig8LDMVX9dXpCC2l", + "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", + "type": "spec/overlays/information/1.0", + "language": "eng", + "attribute_information": { + "d": "Schema digest", + "i": "Credential Issuee", + "passed": "Enables or disables passing" + } + } + ], + "label": [ + { + "d": "ECZc26INzjxVbNo7-hln6xN3HW3e1r6NGDmA5ogRo6ef", + "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", + "type": "spec/overlays/label/1.0", + "language": "eng", + "attribute_categories": [], + "attribute_labels": { + "d": "Schema digest", + "i": "Credential Issuee", + "passed": "Passed" + }, + "category_labels": {} + } + ], + "meta": [ + { + "d": "EOxvie-zslkGmFzVqYAzTVtO7RyFXAG8aCqE0OougnGV", + "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", + "type": "spec/overlays/meta/1.0", + "language": "eng", + "description": "Entrance credential", + "name": "Entrance credential" + } + ] + } +} +``` +_Example 20. Code snippet for an OCA Bundle._ -If well-structured, the metadata in an OCA bundle can facilitate many ways for users to search for information, present results, and even manipulate and present information objects without compromising their integrity. ### Code Tables @@ -1131,7 +1240,7 @@ Internet Assigned Numbers Authority (IANA) [https://www.iana.org/](https://www.i
-[ICAO] +[ICAO]
@@ -1331,29 +1440,3 @@ United Nations. Sustainable Development Goals (SDGs) [https://sdgs.un.org/goals] ## Appendices - -### Appendix A. An example of Metafile content - -```json -{ - "files": { - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] character_encoding": "E3SAKe0z83pfBnhhcZl19PGGKBheb35WeCJ3V6RdqwY8", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] conditional": "Ejx0o0yuwp99vi0V-ssP6URZIXRMGj1oNKIZ1BXi4sHU", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] conformance": "EZv1B5nNl4Rty8CXFTALhr8T6qXeO0CcKliM03sdrkRA", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] entry (en)": "Eri3NLi1fr4QrKoFfTlK31KvWpwrSgGaZ0LLuWYQaZfI", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] entry (fr)": "EY0UZ8aYAPusaWk_TON8c20gHth2tvZs4eWh7XAfXBcY", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] entry_code": "E1mqEb4f6eOMgu5zR857WWlMUwGYwPzZgiM6sWRZkQ0M", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] format": "ESEMKWoKKIf5qvngKecV-ei8MwcQc_pPWCH1FrTWajAM", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] information (en)": "EyzKEWuMs8kspj4r70_Lc8sdppnDx-hb9QqUQywjmDRY", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] information (fr)": "EIGknekgJFqjgQ8ah2NwL8zNWbFrllvXVLqezgB6U3Yg", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] label (en)": "EgBxL29VsxoZso7YFirlMP334ZuC1mkel-lO7TxPxEq8", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] label (fr)": "ED9PH0ZBaOci-nbnYfPgYZWGQdkyWxA-nW3REmB3vhu0", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] layout": "ElJEQGfAvfJEuB7JeNIcvmAPO2DIOaKkpkZyvxO-gQoc", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] meta (en)": "EpW9bQGs0Lk6k5cJikN0Ep-DN6z29fwZIsbVzMBgTlWY", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] meta (fr)": "EIGj0LQKT9-6gCLV2QZVgi4YQZhrUl0-GKbN7sFTCSAI", - "[EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis] unit": "EHDwC_Ucuttrsxh2NVptgBnyG4EMbG5D8QsdbeF9G9-M", - "capture_base-0": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis" - }, - "root": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis" -} -``` From 5dacdac79648cc7c5666a82923efc72fbc4a7c42 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Fri, 17 Jan 2025 17:28:16 +0100 Subject: [PATCH 04/46] docs: Editorial changes --- docs/specification/README.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 533b527..4d855de 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -68,12 +68,6 @@ Contact:
-::: warning Disclaimer -Strictly following DDE Principle 1.4 \[[HCF2022](#ref-HCF2022)\], OCA schema objects MUST be resolvable solely upon the encoded cryptographic digest of their content to ensure objectual integrity. - -All code snippets in this version of the document are in JavaScript Object Notation (JSON) \[[ISO21778](#ref-ISO21778)\] format. However, any serialisation format applies as long as all OCA objects have proper semantics. -::: - ## Introduction _This section is non-normative._ @@ -86,15 +80,15 @@ OCA represents transient objects (domain-agnostic) and persistent schemas (domai #### What is a Capture Base? -A Capture Base is the purest and simplest form of a schema, defining the structural characteristics of a dataset. It is the foundational layer upon which to bind task-specific objects to enhance the meaning of inputted data. +A [Capture Base](#capture-base) is the purest and simplest form of a schema, defining the structural characteristics of a dataset. It is the foundational layer upon which to bind task-specific objects to enhance the meaning of inputted data. #### What are Overlays? -Overlays are task-specific objects that provide cryptographically-bound layers of definitional or contextual metadata to a Capture Base. Any actor interacting with a published Capture Base can use Overlays to transform how inputted data and metadata are displayed to a viewer or guide an agent in applying a custom process to captured data. +[Overlays](#overlays) are task-specific objects that provide cryptographically-bound layers of definitional or contextual metadata to a [Capture Base](#capture-base). Any actor interacting with a published [Capture Base](#capture-base) can use [Overlays](#overlays) to enrich meaning of the data, transform how inputted data and metadata are displayed to a viewer or guide an agent in applying a custom process to captured data. ## OCA object types -An OCA object is either a Capture Base or a task-specific Overlay with a deterministic relationship to a Capture Base. When amalgamated as a Bundle, OCA objects provide the necessary structural, definitional, and contextual information to determine the meaning of inputted data at the time of data capture. +An `OCA object` is either a [Capture Base](#capture-base) or a task-specific [Overlay](#overlays) with a deterministic relationship to a [Capture Base](#capture-base). When amalgamated as a [Bundle](#bundle), OCA objects provide the necessary structural, definitional, and contextual information to determine the meaning of inputted data at the time of data capture. ### Capture Base From 55b790d5e65825339f26e36821a5983ae317721f Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Fri, 17 Jan 2025 17:43:48 +0100 Subject: [PATCH 05/46] docs: Specify non-normative vs normative parts --- docs/specification/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/specification/README.md b/docs/specification/README.md index 4d855de..2b6c12c 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -1122,6 +1122,8 @@ Data presentation MAY involve Semantic, Inputs, and Presentation Overlays. ## Conventions and Definitions +Sections marked as non-normative, along with all authoring guidelines, diagrams, examples, and notes in this specification, are for informational purposes only and are not mandatory for compliance. All other sections of this specification are normative and define the required rules and standards that must be followed to ensure conformity with the OCA Specification. + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted when, and only when, they appear in all capitals, as described in RFC 2119 \[[RFC2119](#ref-RFC2119)\]. ## References From ab3c357d94384361ec002b6cc1ad9805b091a8cc Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Fri, 17 Jan 2025 18:06:25 +0100 Subject: [PATCH 06/46] feat: Allow for SemVer in object type --- docs/specification/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 2b6c12c..ce7c372 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -103,8 +103,8 @@ The Capture Base consists of the following attributes: ```json { - "type": "spec/capture_base/1.0", "classification": "GICS:45102010", + "type": "spec/capture_base/1.0.0", "attributes": { "dateOfBirth": "DateTime", "documentNumber": "Text", @@ -128,11 +128,11 @@ _Example 1. Code snippet for a Capture Base._ #### Type -The `type` attribute identifies the schema object type. +The `type` attribute identifies the schema object type and it's version. ```abnf type = "spec/capture_base/" sem_ver -sem_ver = DIGIT "." DIGIT +sem_ver = DIGIT "." DIGIT "." DIGIT ``` _Listing: ABNF core rules \[[RFC5234](#ref-RFC5234)\]_ From d80cfb70e524357216aed2e3412ed4837a48acaa Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Fri, 17 Jan 2025 18:09:07 +0100 Subject: [PATCH 07/46] feat: Remove PII and classification from capture base - add missing `d` field - remove PII and classification which would be introduced as separate overlays --- docs/specification/README.md | 45 +++++------------------------------- 1 file changed, 6 insertions(+), 39 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index ce7c372..26a3f58 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -92,18 +92,17 @@ An `OCA object` is either a [Capture Base](#capture-base) or a task-specific [Ov ### Capture Base -A Capture Base is a stable base object that defines a single dataset in its purest form, providing a structural base to harmonise data. The object defines attribute names and types. It also contains a flagging block that allows schema issuers to mark potentially dangerous attributes that may capture identifying information about entities (i.e., personally identifiable information (PII) or quasi-identifiable information (QII)). Once flagged, all corresponding data can be treated as high-risk throughout the data lifecycle and encrypted or removed at any stage, reducing the risk of re-identification attacks against blinded datasets. +A `Capture Base` is a stable base object that defines a single dataset in its purest form, providing a structural base to harmonise data. The object defines `attribute names` and `types`. -The Capture Base consists of the following attributes: +The Capture Base consists of the following attributes in that order: -- [ Type ](#type) -- [ Classification ](#classification) -- [ Attributes ](#attributes) -- [ Flagged attributes ](#flagged-attributes) +- `d` - deterministic identifier of the capture base +- [ type ](#type) +- [ attributes ](#attributes) ```json { - "classification": "GICS:45102010", + "d": "EFEDyA__ap51wscacOwATP3c51icUeHT6D0tTbInQI9G", "type": "spec/capture_base/1.0.0", "attributes": { "dateOfBirth": "DateTime", @@ -115,12 +114,6 @@ The Capture Base consists of the following attributes: "photoImage": "Binary", "sex": "Text" }, - "flagged_attributes": [ - "documentNumber", - "fullName", - "dateOfBirth", - "photoImage" - ] } ``` @@ -137,26 +130,6 @@ sem_ver = DIGIT "." DIGIT "." DIGIT _Listing: ABNF core rules \[[RFC5234](#ref-RFC5234)\]_ -#### Classification - -The "classification" attribute is for capturing a standardised classification scheme and taxonomy code to identify the primary sector, area, or topic of a published schema's intended use. Taxonomy codes provide a means for classifying schemas into groupings according to similar functions, markets, products, or services, ultimately leading to better search results for users interested in different categories. - -Note: All classification schemes are supported. RECOMMENDED schemes include the Global Industry Classification Standard (GICS) \[[GICS](#ref-GICS)\] for industry sector classification and the Sustainable Development Goals (SDGs) \[[UNSDG](#ref-UNSDG)\] for the categorisation of humanitarian advocacy and outreach activities. - -```abnf -classification = taxonomy ":" identifier -taxonomy = 1*( ALPHA / DIGIT / "-" ) -identifier = 1*( ALPHA / DIGIT / "-" / "." ) -``` - -_Listing: ABNF core rules_ - -::: tip Example -For the GICS classification: `"classification": "GICS:10101010"` - -For the SDG classification: `"classification": "SDG:1.1"` -::: - #### Attributes The "attributes" attribute maps key-value pairs where the key is the attribute name and the value is the attribute type. @@ -187,12 +160,6 @@ An attribute type determines the attribute's syntax and how attributes of that t - **Array[data type]**: a data type that defines a structure that holds several data items or elements of the same data type. When you want to store many pieces of data that are related and have the same data type, it is often better to use an array instead of many separate variables (e.g., `Array[Text]`, `Array[Numeric]`, etc.). -#### Flagged attributes - -Any attributes defined in a Capture Base that may contain identifying information about entities (i.e., personally identifiable information (PII) or quasi-identifiable information (QII)) can be flagged. - -The Blinding Identity Taxonomy (BIT) \[[KAN2020](#ref-KAN2020)\] is a practical tool for any practitioner whose organisation has custody or control of a dataset containing identifiable information about entities, including a natural person, organisation, or device with signing capabilities that make that entity uniquely identifiable. For example, data protection officers and schema issuers can use the BIT to flag a list of elements which require cryptographic encoding to reduce the risk of identifying a data principal. - ### Overlays Overlays are cryptographically-linked objects that provide layers of task-oriented definitional or contextual information to a Capture Base. Any actor interacting with a published Capture Base can use Overlays to add metadata to the underlying object, transform how information is displayed to a viewer, or guide an agent in applying a custom process to captured data. From edf67d337b3f2aece2d2e76d7bffd7fa3cfaac68 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 10:27:03 +0100 Subject: [PATCH 08/46] feat: Introduce linking to overlay to overlay Allow to link overlay to overlay instead of only capture base. This allows to have linking mechanism of entry overlay to entry codes overlay assuring consistancy. --- docs/specification/README.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 26a3f58..dfc789a 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -162,20 +162,33 @@ An attribute type determines the attribute's syntax and how attributes of that t ### Overlays -Overlays are cryptographically-linked objects that provide layers of task-oriented definitional or contextual information to a Capture Base. Any actor interacting with a published Capture Base can use Overlays to add metadata to the underlying object, transform how information is displayed to a viewer, or guide an agent in applying a custom process to captured data. +`Overlay` as a task-specific object provides layers of definitional or contextual metadata. OCA specification recognize two types of overlays: +- [Semantic overlays](#semantic-overlays) - provide contextual meaning to describe objects and their relationships. +- [Inputs overlays](#inputs-overlays) - provide predefined inputs for data attestations. -Overlays consist of the following attributes: +Which in context of that specification are treated as core overlays which through community consensus are the most important to be included in the specification and moste commenly used. -- [ Capture base ](#capture-base-1) -- [ Type ](#type-1) +OCA Specification intentionaly limits defined overlays in the core specification to the minmum to allow for community driven efforts to create necessary overlays and through dominat design decided which task-specific overlays would make sens. + + +#### Mandatory attributes + +Overlays are cryptographically-linked objects that provide layers of task-oriented definitional or contextual information to a other [OCA Objects](#oca-object-types). Any actor interacting with a published Capture Base can use Overlays to add metadata to the underlying object, transform how information is displayed to a viewer, or guide an agent in applying a custom process to captured data. + +Overlays `MUST` consist of the following attributes in that order: + +- [ capture_base ](#capture-base-1) or [overlay](#overlay) +- [ type ](#type-1) - Overlay-specific attributes - See specific overlay types for more information. -#### Common attributes - ##### Capture base -The `capture_base` attribute contains the SAID of the Capture Base to cryptographically anchor to that parent object. +The `capture_base` attribute contains the SAID of the [Capture Base](#capture-base) to cryptographically anchor to that parent object. + +##### Overlay + +The `overlay` attribute contains the SAID of the [Overlay](#overlays) to cryptographically anchor to that parent object. ##### Type @@ -189,8 +202,12 @@ sem_ver = DIGIT "." DIGIT _Listing: ABNF core rules_ +#### Optional attributes + ##### Language +To indicate language-specific information, some overlays would include a `language` attribute to indicate localization of that overlay. + The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has standardised two lists of language-related codes: the language codes called ISO 639-1 alpha-2 \[[ISO639](#ref-ISO639)\] codes ("Codes for the representation of names of languages") and ISO 3166-1 alpha-2 \[[ISO3166](#ref-ISO3166)\] codes ("Codes for the representation of names of countries"). Both consist of two letters. The language code is written in lowercase while the country code is written in uppercase. However, both ISO classifications may be combined to differentiate regional languages. The `language` attribute MUST contain either the two-letter language code (lowercase) for a national language or the combined language (lowercase)/country (uppercase) code for a regional language or locale. From fc1d713908d775e70c832a9dda7391fe63817a97 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 10:31:06 +0100 Subject: [PATCH 09/46] docs: remove rugby model reference Withotu additional references the model does not bring any value for external reader. The model should be presented as additional recource. --- docs/specification/README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index dfc789a..2635f83 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -219,9 +219,6 @@ _Table 1. An example of ISO standard values for language and combined language/c Semantic overlays provide contextual meaning to describe objects and their relationships. -![Fig 1](/images/spec-fig1.png) -_Figure 1. In a balanced network, semantic overlays determine the meaning and use of what is put in, taken in, or operated on by any process or system._ - ##### Character Encoding Overlay A Character Encoding Overlay defines the process of assigning numbers to graphical characters, especially the written characters of human language, allowing them to be stored, transmitted, and transformed using digital computers. Character encoding using internationally accepted standards permits worldwide interchange of text in electronic form. @@ -442,9 +439,6 @@ _Example 7. Code snippet for a Standard Overlay._ Inputs overlays provide predefined inputs for data attestations. -![Fig 2](/images/spec-fig2.png) -_Figure 2. In a balanced network, inputs overlays determine what is put in, taken in, or operated on by any process or system._ - ##### Cardinality Overlay A Cardinality Overlay defines the minimum and maximum number of values that an attribute can have. For a relationship, the cardinality interval specifies the minimum and maximum number of relationship targets. From e2ab835662500ac07f3f7aa44f90d02c134f1670 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 10:31:31 +0100 Subject: [PATCH 10/46] feat: remove information overlay Remove information overlay in favour of presentation layer. See ORFg findings. --- docs/specification/README.md | 32 -------------------------------- 1 file changed, 32 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 2635f83..2f6bd4a 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -299,38 +299,6 @@ The inputted format values are dependent on the following core data types as def _Example 3. Code snippet for a Format Overlay._ -##### Information Overlay - -_[language-specific object]_ - -An Information Overlay defines attribute field descriptions and usage notes to assist the data entry process or to add context to presented data. - -In addition to the `capture_base`, `type`, and `language` attributes (see [Common attributes](#common-attributes)), the Information Overlay MUST include the following attribute: - -- `attribute_information` - - The `attribute_information` attribute maps key-value pairs where the key is the attribute name and the value is the informational prose in a specific language. - -```json -{ - "capture_base":"EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type":"spec/overlays/information/1.0", - "language":"en", - "attribute_information":{ - "dateOfBirth":"Holder’s date of birth as recorded by the issuing State or organization.", - "documentNumber":"Unique identification number of the document.", - "documentType":"The word for "passport" in the language of the issuing State or organization.", - "fullName":"Full name of the passport holder.", - "height":"Recorded height of the passport holder.", - "issuingState":"Name of the State or organization responsible for issuing the passport.", - "photoImage":"Portrait image of the passport holder.", - "sex":"Sex of the passport holder." - } -} -``` - -_Example 4. Code snippet for an Information Overlay (language: en)._ - ##### Label Overlay _[language-specific object]_ From 422939f3cba37083167544801f9792aae329561f Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 10:37:05 +0100 Subject: [PATCH 11/46] feat: remove transformation overlay Move transformation overlay to community overlays. --- docs/specification/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 2f6bd4a..f138b65 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -641,10 +641,6 @@ and MUST include the following attribute: _Example 13. Code snippet for a Unit Overlay._ -#### Transformation Overlays - -Transformation overlays provide information to convert data from one format or structure to another, such as raw data to processed, or unstructured to structured. - ##### Attribute Mapping Overlay An Attribute Mapping Overlay defines attribute mappings between two distinct data models. Data mapping provides a preliminary step for data integration tasks, including data transformation or data mediation between a data source and a destination or consolidation of multiple databases into a single database and identifying redundant columns of data for consolidation or elimination. From 34bb431af235790ff968ae3d94c000619aa55b24 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 10:47:05 +0100 Subject: [PATCH 12/46] feat: remove presentation overlay --- docs/specification/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index f138b65..041cf09 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -731,10 +731,6 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] _Example 17. Code snippet for a Unit Mapping Overlay._ -#### Presentation Overlays - -Presentation overlays provide information to display digital documents at the application layer, including digital forms and credentials. - ##### Layout Overlay ::: danger [Currently under review by Decentralised Semantics Working Group] From e42540255d5e07785df4511b37efeb4512415f4a Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 10:47:26 +0100 Subject: [PATCH 13/46] feat: remove layout overlay --- docs/specification/README.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 041cf09..f75fe35 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -731,17 +731,6 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] _Example 17. Code snippet for a Unit Mapping Overlay._ -##### Layout Overlay - -::: danger [Currently under review by Decentralised Semantics Working Group] -::: - -A Layout Overlay defines presentation information required by an application to display a digital document, including a digital form or credential. - -::: warning Disclaimer: -Collaborators in several open communities have shown an interest in leveraging OCA’s "task-specific" ethos to work on new overlay types to ensure that data presentation (see [Presentation](#presentation)) is both extensible and interoperable. Deprecation of the Layout Overlay in favour of a more granular approach is likely in the future. -::: - ##### Sensitive Overlay A Sensitive Overlay defines attributes not necessarily flagged in the Capture Base that need protecting against unwarranted disclosure. For example, data that requires protection for legal or ethical reasons, personal privacy, or proprietary considerations. From 2cc67c15ef797c957786abe756a9e984e7c18370 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 10:58:05 +0100 Subject: [PATCH 14/46] feat: enahnce sensitive overlay to replace flagging from capture base --- docs/specification/README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index f75fe35..6c3614e 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -733,7 +733,12 @@ _Example 17. Code snippet for a Unit Mapping Overlay._ ##### Sensitive Overlay -A Sensitive Overlay defines attributes not necessarily flagged in the Capture Base that need protecting against unwarranted disclosure. For example, data that requires protection for legal or ethical reasons, personal privacy, or proprietary considerations. +A Sensitive Overlay is a specialized construct used to identify and flag attributes that require protection against unauthorized or unwarranted disclosure. Attributes marked by a Sensitive Overlay typically include data subject to legal, ethical, or privacy-related considerations, including but not limited to Personally Identifiable Information (PII), Quasi-Identifiable Information (QII)) or proprietary information. + +Sensitive Overlays are integral to ensuring compliance with legal and ethical standards while supporting robust data governance. Implementers must incorporate mechanisms to respect and enforce the protections designated by these overlays to maintain conformity with the OCA Specification. + +The Blinding Identity Taxonomy (BIT) [KAN2020](#ref-KAN2020) is a practical tool for any practitioner whose organisation has custody or control of a dataset containing identifiable information about entities, including a natural person, organisation, or device with signing capabilities that make that entity uniquely identifiable. For example, data protection officers and schema issuers can use the BIT to flag a list of elements which require cryptographic encoding to reduce the risk of identifying a data principal. + In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Sensitive Overlay MUST include the following attribute: From 7f1d5ae198ae417e743e6e07870db43a2b840713 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 10:59:27 +0100 Subject: [PATCH 15/46] docs: remove non-normative section about basic concept --- docs/.vuepress/public/images/spec-fig4.png | Bin 13079 -> 0 bytes docs/specification/README.md | 36 --------------------- 2 files changed, 36 deletions(-) delete mode 100644 docs/.vuepress/public/images/spec-fig4.png diff --git a/docs/.vuepress/public/images/spec-fig4.png b/docs/.vuepress/public/images/spec-fig4.png deleted file mode 100644 index 3a809752295840f6ea3ebe6f4c7b9d014ce06ecb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 13079 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 diff --git a/docs/specification/README.md b/docs/specification/README.md index 6c3614e..8b45b63 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -1016,42 +1016,6 @@ _Example 23. Code snippet for a Code Table for Unit mappings._ Code Table for Unit mappings is in denormalised form, meaning that the conversion between units and unit prefixes is pre-defined for all standard unit conversions for maximum efficiency. -## Basic concepts - -_This section is non-normative._ - -Characters provide the essential elements required for written language in the physical world. In the digital world, stored sequences of bytes known as "data" represent these elements. However, without a system of interpretation, data has no inherent morphological, definitional, or contextual meaning. This interpretation is provided by "metadata", sets of data that provide meaning to any stored sequence of bytes. - -OCA is a core utility architecture for capturing the metadata necessary to interpret and preserve the meaning of inputted data. In addition, the architecture introduces a comprehensive solution to support data validation, transformation, and presentation requirements throughout a data lifecycle. - -![Fig 4](/images/spec-fig4.png) - -_Figure 4. Universal OCA lifecycle._ - -### Capture - -Data capture is the process of collecting structured and unstructured information electronically and converting it into data readable by a computer. - -Data capture MAY involve Semantic, Inputs, and Presentation Overlays. - -### Validation - -Data validation is the process of checking the integrity, accuracy and structure of data before it is used for a business operation. - -Data validation MAY involve Semantic and Inputs Overlays. - -### Transformation - -Data transformation is the process of converting data from one format to another, typically from the format of a source system into the required format of a destination system. - -Data transformation MUST involve Transformation Overlays. - -### Presentation - -Data presentation is the process of using various graphical formats to visually represent the relationship between two or more data sets so that, based on the results, the reader or verifier can make an informed decision. - -Data presentation MAY involve Semantic, Inputs, and Presentation Overlays. - ## Conventions and Definitions Sections marked as non-normative, along with all authoring guidelines, diagrams, examples, and notes in this specification, are for informational purposes only and are not mandatory for compliance. All other sections of this specification are normative and define the required rules and standards that must be followed to ensure conformity with the OCA Specification. From 39e345bf1124179cc8350e0f09365df8f332e502 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 11:01:52 +0100 Subject: [PATCH 16/46] docs: move conventions section to the begining --- docs/specification/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 8b45b63..7f5750d 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -68,6 +68,12 @@ Contact: +## Conventions and Definitions + +Sections marked as non-normative, along with all authoring guidelines, diagrams, examples, and notes in this specification, are for informational purposes only and are not mandatory for compliance. All other sections of this specification are normative and define the required rules and standards that must be followed to ensure conformity with the OCA Specification. + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted when, and only when, they appear in all capitals, as described in RFC 2119 \[[RFC2119](#ref-RFC2119)\]. + ## Introduction _This section is non-normative._ @@ -1016,12 +1022,6 @@ _Example 23. Code snippet for a Code Table for Unit mappings._ Code Table for Unit mappings is in denormalised form, meaning that the conversion between units and unit prefixes is pre-defined for all standard unit conversions for maximum efficiency. -## Conventions and Definitions - -Sections marked as non-normative, along with all authoring guidelines, diagrams, examples, and notes in this specification, are for informational purposes only and are not mandatory for compliance. All other sections of this specification are normative and define the required rules and standards that must be followed to ensure conformity with the OCA Specification. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted when, and only when, they appear in all capitals, as described in RFC 2119 \[[RFC2119](#ref-RFC2119)\]. - ## References ### Normative References From 9dd8c138a389f5d7e398f654207444d7d343834d Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 12:13:41 +0100 Subject: [PATCH 17/46] docs: editorial changes to improve clarity --- docs/specification/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 7f5750d..8d40335 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -94,11 +94,11 @@ A [Capture Base](#capture-base) is the purest and simplest form of a schema, def ## OCA object types -An `OCA object` is either a [Capture Base](#capture-base) or a task-specific [Overlay](#overlays) with a deterministic relationship to a [Capture Base](#capture-base). When amalgamated as a [Bundle](#bundle), OCA objects provide the necessary structural, definitional, and contextual information to determine the meaning of inputted data at the time of data capture. +An `OCA object` is either a [Capture Base](#capture-base) or a task-specific [Overlay](#overlays) with a deterministic relationship to a [Capture Base](#capture-base) or another [Overlay](#overlays). When amalgamated as a [Bundle](#bundle), OCA objects provide the necessary structural, definitional, and contextual information to determine the meaning of inputted data at the time of data capture. ### Capture Base -A `Capture Base` is a stable base object that defines a single dataset in its purest form, providing a structural base to harmonise data. The object defines `attribute names` and `types`. +A `Capture Base` is a base object that defines a single dataset in its purest form, providing a structural base to harmonise data. The object defines attribute names and types. The Capture Base consists of the following attributes in that order: @@ -127,7 +127,7 @@ _Example 1. Code snippet for a Capture Base._ #### Type -The `type` attribute identifies the schema object type and it's version. +The `type` attribute specifies the schema object type and its associated version. The version aligns with the corresponding OCA specification version, ensuring that the schema object remains compatible with the specified OCA specification. ```abnf type = "spec/capture_base/" sem_ver From 8077b64eabae6cb2ad3989d9f205c9765e0851bc Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 12:20:13 +0100 Subject: [PATCH 18/46] docs: improve attribute name description and add ABNF --- docs/specification/README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 8d40335..66851cf 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -142,7 +142,20 @@ The "attributes" attribute maps key-value pairs where the key is the attribute n ##### Attribute name -An attribute name is a string that uniquely identifies an attribute within an OCA layer and is used to reference that attribute by other layers throughout the OCA bundle. +An attribute name is a string that uniquely identifies an attribute within an OCA layer and is used to reference that attribute by other layers throughout the OCA bundle. The string can be any valid Unicode code point. +Example of a valid attribute name: +- `FullName` +- `person/name/fullName` +- `王小明` +- `550e8400-e29b-41d4-a716-446655440000` + +```abnf +string = 1*(character) +character = %x0000-10FFFF +``` + +_Listing: ABNF representation of the attribute name_ + ##### Attribute type From ded80ebb281a032458b2ea8f0cc9a5ea72cf4961 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 12:25:55 +0100 Subject: [PATCH 19/46] docs: remove note about ISO datetime recomendation. It is not needed, and we may add some explanation how implementation handles time internally but should not be relevant for the specification. --- docs/specification/README.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 66851cf..4e0d64a 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -167,16 +167,6 @@ An attribute type determines the attribute's syntax and how attributes of that t - **Boolean**: a data type where the data only has two possible variables: true or false. In computer science, Boolean is an identification classifier for calculating logical truth values and algebraic variables. - **Binary**: a data type that defines a binary code signal, a series of electrical pulses representing numbers, characters, and performed operations. Based on a binary number system, each digit position represents a power of two (e.g., 4, 8, 16, etc.). A set of four binary digits or bits in binary code represents each decimal number (0 to 9). Each digit has two possible states: off and on (usually symbolised by 0 and 1). Combining basic Boolean algebraic operations on binary numbers makes it possible to represent each of the four fundamental arithmetic operations of addition, subtraction, multiplication, and division. - **DateTime**: a data type that defines the number of seconds or clock ticks that have elapsed since the defined epoch for that computer or platform. Common formats include dates (e.g., YYYY-MM-DD), times (e.g., hh:mm:ss), dates and times concatenated (e.g., `YYYY-MM-DDThh:mm:ss.sss+zz:zz`), and durations (e.g., `PnYnMnD`). - - Note: The ISO 8601 \[[ISO8601](#ref-ISO8601)\] date and time format is the RECOMMENDED representation format for the dateTime data type, in which the Unix epoch is `1970-01-01T00:00:00Z`. - - :::tip For the Unix epoch example: - Data type: `DateTime`
- Character encoding: `UTF-8` (default)
- Standard: `ISO 8601`
- Format: `YYYY-MM-DDThh:mm:ssZ` - ::: - - **Array[data type]**: a data type that defines a structure that holds several data items or elements of the same data type. When you want to store many pieces of data that are related and have the same data type, it is often better to use an array instead of many separate variables (e.g., `Array[Text]`, `Array[Numeric]`, etc.). ### Overlays From 941971ce95451c8cfd948301e05986995d8af7b7 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 12:46:02 +0100 Subject: [PATCH 20/46] docs: improve overlay type description and align with SemVer --- docs/specification/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 4e0d64a..c3e6585 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -201,12 +201,12 @@ The `overlay` attribute contains the SAID of the [Overlay](#overlays) to cryptog ##### Type -The `type` attribute identifies the schema object type. +The `type` attribute identifies the schema object type. The version aligns with the corresponding OCA specification version, ensuring that the object remains compatible with the specified OCA specification. ```abnf type = "spec/overlay/" overlay_name "/" sem_ver overlay_name = ALPHA -sem_ver = DIGIT "." DIGIT +sem_ver = DIGIT "." DIGIT "." DIGIT ``` _Listing: ABNF core rules_ From 6fbbcbea320cd3d00b39dba93de1a69cad4804b3 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Mon, 20 Jan 2025 13:06:17 +0100 Subject: [PATCH 21/46] feat: Use 639-3 for language codes - add example - update 639 iso link to point to latest spec version - enforce 639-3 as a main codes for languges in overlays - clean dead references from ISO which are not used --- docs/specification/README.md | 43 ++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index c3e6585..e187ef2 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -217,13 +217,26 @@ _Listing: ABNF core rules_ To indicate language-specific information, some overlays would include a `language` attribute to indicate localization of that overlay. -The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has standardised two lists of language-related codes: the language codes called ISO 639-1 alpha-2 \[[ISO639](#ref-ISO639)\] codes ("Codes for the representation of names of languages") and ISO 3166-1 alpha-2 \[[ISO3166](#ref-ISO3166)\] codes ("Codes for the representation of names of countries"). Both consist of two letters. The language code is written in lowercase while the country code is written in uppercase. However, both ISO classifications may be combined to differentiate regional languages. +The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has standardised comprehansive list of language-related codes called ISO 639-3. -The `language` attribute MUST contain either the two-letter language code (lowercase) for a national language or the combined language (lowercase)/country (uppercase) code for a regional language or locale. - -![Table 1](/images/spec-table1.png) -_Table 1. An example of ISO standard values for language and combined language/country codes._ +The `language` attribute MUST contain the three-letter language code (lowercase) according to the [ISO 639-3](#ref-ISO639). +```json +{ + "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", + "type": "spec/overlays/label/1.0.1", + "language": "pol", + "attributes": { + "dateOfBirth": "Data urodzenia", + "documentNumber": "Numer paszportu", + "documentType": "Typ dokumentu", + "fullName": "Imię i nazwisko", + "height": "Wzrost", + "issuingState": "Wydający państwo", + "photoImage": "Zdjęcie" +} +``` +_Example: Code snipet of lable overlay with language attribute set to polish_ #### Semantic Overlays Semantic overlays provide contextual meaning to describe objects and their relationships. @@ -1175,25 +1188,7 @@ International Organization for Standardization (ISO) [https://www.iso.org/home.h
-ISO 639-1:2002, Codes for the representation of names of languages — Part 1: Alpha-2 code (2019) [https://www.iso.org/standard/22109.html](https://www.iso.org/standard/22109.html) - -
- -
-[ISO3166] -
-
- -ISO 3166-1:2020, Codes for the representation of names of countries and their subdivisions — Part 1: Country code (2020) [https://www.iso.org/standard/72482.html](https://www.iso.org/standard/72482.html) - -
- -
-[ISO7501] -
-
- -ISO/IEC 7501-1:2008, Identification cards — Machine readable travel documents — Part 1: Machine-readable passport (2021) [https://www.iso.org/standard/45562.html](https://www.iso.org/standard/45562.html) +ISO 639-1:2002, Codes for the representation of names of languages — Part 3 (2007) [https://www.iso.org/standard/74575.html](https://www.iso.org/standard/74575.html)
From edef45a3cc079d97ac7440c347037ccb38a87418 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 6 Feb 2025 09:04:13 +0100 Subject: [PATCH 22/46] chore: Fix links and improve identation --- docs/.vuepress/config.js | 2 +- docs/.vuepress/public/images/spec-fig4.png | Bin 0 -> 13079 bytes docs/specification/README.md | 55 +++++++++++---------- docs/specification/v1.0.1.md | 4 +- 4 files changed, 31 insertions(+), 30 deletions(-) create mode 100644 docs/.vuepress/public/images/spec-fig4.png diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b82b159..34f6507 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -70,7 +70,7 @@ export default defineUserConfig({ text: "Specification", children: [ { - text: "OCA v1.0.1", + text: "OCA v1.0.2", link: "/specification/README.md", }, { diff --git a/docs/.vuepress/public/images/spec-fig4.png b/docs/.vuepress/public/images/spec-fig4.png new file mode 100644 index 0000000000000000000000000000000000000000..3a809752295840f6ea3ebe6f4c7b9d014ce06ecb GIT binary patch literal 13079 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 literal 0 HcmV?d00001 diff --git a/docs/specification/README.md b/docs/specification/README.md index e187ef2..4f8c9b7 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -15,57 +15,58 @@ description: Official OCA specification
Latest published version:
-
+
-[https://oca.colossi.network/specification/](https://oca.colossi.network/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.pdf)) + [https://oca.colossi.network/specification/](/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.0.2.pdf)) -
+
-Author: + Previous published version:
-
+
-Paul Knowles ([ Human Colossus Foundation ](https://humancolossus.foundation/)) + [https://oca.colossi.network/specification/v1.0.1](/specification/v1.0.1) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.0.1.pdf)) -
+
-Editors: + Contributors:
-
+
-Ryan Barrett (Stratosoft LLC) + Paul Knowles ([ Human Colossus Foundation ](https://humancolossus.foundation/)) -Robert Mitwicki ([ Human Colossus Foundation ](https://humancolossus.foundation/)) + Ryan Barrett (Stratosoft LLC) -Michal Pietrus ([ ArgonAUTHs ](https://argonauths.eu/)) + Robert Mitwicki ([ Human Colossus Foundation ](https://humancolossus.foundation/)) + Michal Pietrus ([ ArgonAUTHs ](https://argonauths.eu/)) -Marcin Olichwiruk ([ ArgonAUTHs ](https://argonauths.eu/)) + Marcin Olichwiruk ([ ArgonAUTHs ](https://argonauths.eu/)) -Philippe Page ([ Human Colossus Foundation ](https://humancolossus.foundation/)) + Philippe Page ([ Human Colossus Foundation ](https://humancolossus.foundation/)) -
+
-Copyrights: + Copyrights:
-
-Human Colossus Foundation, EUPL v1.2 licence. -
+
+ Human Colossus Foundation, EUPL v1.2 licence. +
-Governance: + Governance:
-
+
-The Decentralised Semantics Working Group maintains the OCA specification at [ Human Colossus Foundation ](https://humancolossus.foundation). Comments regarding this specification can be provided as issues on the official [ OCA Github ](https://github.com/the-human-colossus-foundation/oca-spec/issues). + The Decentralised Semantics Working Group maintains the OCA specification at [ Human Colossus Foundation ](https://humancolossus.foundation). Comments regarding this specification can be provided as issues on the official [ OCA Github ](https://github.com/the-human-colossus-foundation/oca-spec/issues). -
+
-Contact: + Contact:
-
+
-[ contact@humancolossus.org ](mailto:contact@humancolossus.org) + [ contact@humancolossus.org ](mailto:contact@humancolossus.org) -
+ ## Conventions and Definitions diff --git a/docs/specification/v1.0.1.md b/docs/specification/v1.0.1.md index 1a353a5..46cc9f7 100644 --- a/docs/specification/v1.0.1.md +++ b/docs/specification/v1.0.1.md @@ -17,7 +17,7 @@ description: Official OCA specification
-[https://oca.colossi.network/specification/](https://oca.colossi.network/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.pdf)) +[https://oca.colossi.network/specification/](/specification/) ([Download as PDF](https://humancolossus.foundation/s/HCF-Overlays-Capture-Architecture-OCA-v1.pdf))
@@ -1131,7 +1131,7 @@ Internet Assigned Numbers Authority (IANA) [https://www.iana.org/](https://www.i
-[ICAO] +[ICAO]
From c4812de31e9a75f129106f5085eaf05250de02eb Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 6 Feb 2025 09:30:02 +0100 Subject: [PATCH 23/46] feat: remove categories from label overlay Categories are part of the presentation layer and should not be part of the label overlay. Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 33 +++++++++++---------------------- 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 4f8c9b7..35b4535 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -172,13 +172,19 @@ An attribute type determines the attribute's syntax and how attributes of that t ### Overlays -`Overlay` as a task-specific object provides layers of definitional or contextual metadata. OCA specification recognize two types of overlays: +`Overlay` as a task-specific object provides layers of definitional or contextual metadata. OCA specification recognize two core types of overlays: - [Semantic overlays](#semantic-overlays) - provide contextual meaning to describe objects and their relationships. - [Inputs overlays](#inputs-overlays) - provide predefined inputs for data attestations. -Which in context of that specification are treated as core overlays which through community consensus are the most important to be included in the specification and moste commenly used. +In the context of this specification, these are considered **core overlays**, which, through **community consensus**, are deemed the most essential for inclusion and are among the most commonly used. + +The **OCA Specification** intentionally limits the number of **predefined core +overlays** to a **minimum**, allowing the community to take the lead in +developing additional overlays as needed. This approach fosters a **dominant +design** process, enabling the community to determine which **task-specific +overlays** are most meaningful and valuable. See [Community overlays](#community-overlays) for more details. + -OCA Specification intentionaly limits defined overlays in the core specification to the minmum to allow for community driven efforts to create necessary overlays and through dominat design decided which task-specific overlays would make sens. #### Mandatory attributes @@ -334,21 +340,11 @@ In addition to the `capture_base`, `type`, and `language` attributes (see [Commo The `attribute_labels` attribute maps key-value pairs where the key is the attribute name and the value is a human-meaningful attribute label in a specific language. -and MAY include the following attributes: - -- `attribute_categories` - - The `attribute_categories` attribute contains category identifiers. - -- `category_labels ` - - The `attribute_categories` attribute maps key-value pairs where the key is the attribute name and the value is a human-meaningful category label in a specific language. - ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/label/1.0", - "language": "en", + "language": "eng", "attribute_labels": { "dateOfBirth": "Date of birth", "documentNumber": "Passport Number", @@ -359,13 +355,6 @@ and MAY include the following attributes: "photoImage": "Portrait image", "sex": "Sex" }, - "attribute_categories": ["_cat-1_", "_cat-2_", "_cat-3_", "_cat-4_"], - "category_labels": { - "_cat-1_": "Mandatory header", - "_cat-2_": "Mandatory personal data elements", - "_cat-3_": "Mandatory identification feature", - "_cat-4_": "Optional data elements" - } } ``` @@ -393,7 +382,7 @@ and MAY include other attributes at the discretion of the overlay producer, such { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/meta/1.0", - "language": "en", + "language": "eng", "name": "Digital Passport", "description": "An example of a Digital Passport schema", "affiliation": "The Government of Antarctica" From 699e68a9d2fc00297e5c6a0a9b6fc2d8f7fbcced Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 6 Feb 2025 09:30:49 +0100 Subject: [PATCH 24/46] feat: move conditional overlay as community overlay Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 67 ------------------------------------ 1 file changed, 67 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 35b4535..b403960 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -450,73 +450,6 @@ Note that `n` and `m` are positive integers. _Example 8. Code snippet for a Cardinality Overlay._ -##### Conditional Overlay - -A Conditional Overlay defines conditional expressions (or rules) that trigger specific computations or actions depending on whether, upon evaluation, programmer-defined Boolean expressions return true or false values. Met conditions can have a direct impact on data capture and data validation processes where, for example, expressions: - -- MAY facilitate schema extensions; -- MAY enable schema abstractions; -- MAY activate validation processes. - -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Conditional Overlay MUST include the following attributes: - -- `attribute_conditions ` - - The `attribute_conditions` attribute maps key-value pairs where the key is the attribute name and the value is the conditional expression. - - Expressions MAY contain placeholders to be substituted by values defined by the `attribute_dependencies` attribute. - - ```abnf - conditional-statement = 1*conditional-expression - conditional-expression = equality-relational / equality-relational logical-operator - equality-relational = equality-expression / relational-expression - logical-operator = *SP ("and" / "or") *SP - equality-expression = assignment eql-op assignment - eql-op = "=="/ "~=" - relational-expression = assignment relational-op assignment - relational-op = "<" / ">" / "<=" / ">=" - assignment = *SP (ALPHA / DIGIT / "\${" DIGIT "}") *SP - ``` - - _Listing: ABNF core rules_ - -- `attribute_dependencies ` - - The `attribute_dependencies` attribute maps key-value pairs where the key is the attribute name and the value is an array value which triggers the evaluation process of the conditional expression defined by the `attribute_conditions` attribute. - -```json -{ - "capture_base":"EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type":"spec/overlays/conditional/1.0", - "attribute_conditions":{ - "idCardNumber":"${0}=='ID_CARD'", - "passportNumber":"${0}=='PASSPORT'" - }, - "attribute_dependencies":{ - "idCardNumber":[ - "documentType" - ], - "passportNumber":[ - "documentType" - ] - } -} - -// Entry code overlay with options for `documentType` -{ - "capture_base":"EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type":"spec/overlays/entry_code/1.0", - "attribute_entry_codes":{ - "documentType":[ - "ID_CARD", - "PASSPORT" - ] - } -} -``` - -_Example 9. Code snippet for a Conditional Overlay. When the condition matches for `idCardNumber,` that is, `documentType` matches `ID_CARD,` the default behavior is to apply other overlays to `idCardNumber,` i.e., conformance. `${0}` is an integer placeholder that refers to a replacement value during the substitution process. The `attribute_dependencies` attribute provides that replacement value through an array of attributes. Therefore, the placeholder's integer value refers to an array index that points to the value. In other words, `documentType` is bound by the integer placeholder, which triggers the evaluation process of the expression._ - ##### Conformance Overlay A Conformance Overlay indicates whether data entry for each attribute is mandatory or optional. From c4969f608f8cd8561a0276b67ba2c22cdeef2588 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 6 Feb 2025 09:48:52 +0100 Subject: [PATCH 25/46] chore: clarity about language common attribute Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index b403960..3c4c4cf 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -218,11 +218,12 @@ sem_ver = DIGIT "." DIGIT "." DIGIT _Listing: ABNF core rules_ -#### Optional attributes +#### Common attributes ##### Language To indicate language-specific information, some overlays would include a `language` attribute to indicate localization of that overlay. +Those overlays are marked in the specification as `[lagnauge-specific object]` The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has standardised comprehansive list of language-related codes called ISO 639-3. @@ -332,9 +333,9 @@ _Example 3. Code snippet for a Format Overlay._ _[language-specific object]_ -A Label Overlay defines attribute and category labels. For example, for an attribute named `dateOfBirth`, you may wish to display the label as `Date of birth`, which is more meaningful and user-friendly when displayed to an end user in places such as form inputs and error messages. +A Label Overlay defines human readable attribute names. For example, for an attribute named `dateOfBirth`, you may wish to call it `Date of birth`, which is more meaningful and user-friendly when inspected by human. -In addition to the `capture_base`, `type`, and `language` attributes (see [Common attributes](#common-attributes)), the Label Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes) and [language](#language), the Label Overlay MUST include the following attribute: - `attribute_labels` From beed75a243f960b55d0b06d0699da8209ea1782e Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 6 Feb 2025 09:49:09 +0100 Subject: [PATCH 26/46] chore: fix versioning in examples Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 3c4c4cf..ce7efe8 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -442,7 +442,7 @@ Note that `n` and `m` are positive integers. ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/cardinality/1.0", + "type": "spec/overlays/cardinality/1.0.2", "attr_cardinality": { "documentType": "1-2" } @@ -464,7 +464,7 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/conformance/1.0", + "type": "spec/overlays/conformance/1.0.2", "attribute_conformance": { "dateOfBirth": "M", "documentNumber": "M", From 942a5ba8e11a0a78cb080d85529b89300772ba9d Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 6 Feb 2025 09:55:03 +0100 Subject: [PATCH 27/46] chore: align description with new structure Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 44 ++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index ce7efe8..d1faa18 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -232,7 +232,7 @@ The `language` attribute MUST contain the three-letter language code (lowercase) ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/label/1.0.1", + "type": "spec/overlays/label/1.0.2", "language": "pol", "attributes": { "dateOfBirth": "Data urodzenia", @@ -253,7 +253,7 @@ Semantic overlays provide contextual meaning to describe objects and their relat A Character Encoding Overlay defines the process of assigning numbers to graphical characters, especially the written characters of human language, allowing them to be stored, transmitted, and transformed using digital computers. Character encoding using internationally accepted standards permits worldwide interchange of text in electronic form. -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Character Encoding Overlay MAY include the following attributes: +In addition to the [Mandatory attributes](#mandatory-attributes), the Character Encoding Overlay MUST include at least one of the following attributes: - `default_character_encoding` @@ -286,7 +286,7 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/character_encoding/1.0", + "type": "spec/overlays/character_encoding/1.0.2", "default_character_encoding": "utf-8", "attribute_character_encoding": { "photoImage": "base64" @@ -300,7 +300,7 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] A Format Overlay defines an input and display format for data fields. The data format enables conversion of the input buffer to the program variable and displays program variable data to form fields. -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Format Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Format Overlay MUST include the following attribute: - `attribute_formats` @@ -317,7 +317,7 @@ The inputted format values are dependent on the following core data types as def ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/format/1.0", + "type": "spec/overlays/format/1.0.2", "attribute_formats": { "dateOfBirth": "YYYY-MM-DD", "documentNumber": "[A-Z0-9]{9}", @@ -344,7 +344,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes) and [language]( ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/label/1.0", + "type": "spec/overlays/label/1.0.2", "language": "eng", "attribute_labels": { "dateOfBirth": "Date of birth", @@ -367,7 +367,7 @@ _[language-specific object]_ A Meta Overlay defines any language-specific information about a schema. It is used for discovery and identification and includes elements such as the schema name and description. -In addition to the `capture_base`, `type`, and `language` attributes (see [Common attributes](#common-attributes)), the Meta Overlay SHOULD include the following attributes: +In addition to the [Mandatory attributes](#mandatory-attributes) and [language](#language), the Meta Overlay SHOULD include the following attributes: - `name` @@ -382,7 +382,7 @@ and MAY include other attributes at the discretion of the overlay producer, such ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/meta/1.0", + "type": "spec/overlays/meta/1.0.2", "language": "eng", "name": "Digital Passport", "description": "An example of a Digital Passport schema", @@ -396,7 +396,7 @@ _Example 6. Code snippet for a Meta Overlay (language: en)._ A Standard Overlay defines a documented agreement or technical specification published by a standards organisation used to represent, format, define, structure, tag, transmit, manipulate, use, and manage data. -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Standard Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Standard Overlay MUST include the following attribute: - `attr_standards` @@ -407,7 +407,7 @@ There are many international standards organisations establishing tens of thousa ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/standard/1.0", + "type": "spec/overlays/standard/1.0.2", "attr_standards": { "dateOfBirth": "ISO 8601" } @@ -424,7 +424,7 @@ Inputs overlays provide predefined inputs for data attestations. A Cardinality Overlay defines the minimum and maximum number of values that an attribute can have. For a relationship, the cardinality interval specifies the minimum and maximum number of relationship targets. -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Cardinality Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Cardinality Overlay MUST include the following attribute: - `attr_cardinality` @@ -455,7 +455,7 @@ _Example 8. Code snippet for a Cardinality Overlay._ A Conformance Overlay indicates whether data entry for each attribute is mandatory or optional. -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Conformance Overlay MAY include the following attributes: +In addition to the [Mandatory attributes](#mandatory-attributes), the Conformance Overlay MAY include the following attributes: - `attribute_conformance ` @@ -487,7 +487,7 @@ An Entry Code Overlay defines the entry keys in a series of key-value pairs stor ![Table 2](/images/spec-table2.png) _Table 2. An example of how the values in an array of key-value pairs provided by an Entry Code Overlay subsequently define a set of pre-defined entry keys in a nested series of key-value pairs. The specified values are often standardised categorisation codes, valuable data inputs for statistical analysis, machine learning (ML), and artificial intelligence (AI) algorithms._ -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Entry Code Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Entry Code Overlay MUST include the following attribute: - `attribute_entry_codes ` @@ -500,7 +500,7 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/entry_code/1.0", + "type": "spec/overlays/entry_code/1.0.2", "attribute_entry_codes": { "documentType": ["PE", "PM"], "issuingState": "EGyWgdQR9dW_I5oHlHBMoO9AA_eMeb2p3XzcCRCBbKCM", @@ -520,7 +520,7 @@ An Entry Overlay defines the entry values in a series of key-value pairs stored ![Table 3](/images/spec-table3.png) _Table 3. An example of how an Entry Overlay can leverage a set of pre-defined entry keys in a nested series of key-value pairs provided by an Entry Code Overlay to provide human-meaningful values in a specified national or regional language._ -In addition to the `capture_base`, `type`, and `language` attributes (see [Common attributes](#common-attributes)), the Entry Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), and [languag](#language), the Entry Overlay MUST include the following attribute: - `attribute_entries` @@ -533,8 +533,8 @@ In addition to the `capture_base`, `type`, and `language` attributes (see [Commo ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/entry/1.0", - "language": "en", + "type": "spec/overlays/entry/1.0.2", + "language": "eng", "attribute_entries": { "documentType": { "PE": "DIPLOMATIC PASSPORT", @@ -562,7 +562,7 @@ Adopted by the 11th General Conference on Weights and Measures (CGPM) in 1960, i _Figure 3. The seven defining constants of the SI._ -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Unit Overlay SHOULD include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Unit Overlay SHOULD include the following attribute: - `metric_system` @@ -577,7 +577,7 @@ and MUST include the following attribute: ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/unit/1.0", + "type": "spec/overlays/unit/1.0.2", "metric_system": "SI", "attribute_units": { "height": "cm" @@ -594,7 +594,7 @@ An Attribute Mapping Overlay defines attribute mappings between two distinct dat ```json { "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc", - "type": "spec/overlays/mapping/1.0", + "type": "spec/overlays/mapping/1.0.2", "attribute_mapping": { "first_name": "firstName", "last_name": "surname" @@ -611,7 +611,7 @@ An Entry Code Mapping Overlay defines the entry key mappings between two distinc ```json { "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc", - "type": "spec/overlays/entry_code_mapping/1.0", + "type": "spec/overlays/entry_code_mapping/1.0.2", "attr_entry_codes_mapping": { "country_code": [ "AFG:AF", @@ -638,7 +638,7 @@ A Subset Overlay defines a customised version of a published schema containing a ```json { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/subset/1.0", + "type": "spec/overlays/subset/1.0.2", "attributes": ["dateOfBirth", "documentNumber", "documentType"] } ``` From b97cc7827817f31860aff94750d577c32eecba63 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 6 Feb 2025 10:09:24 +0100 Subject: [PATCH 28/46] feat: add community overlay section Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/specification/README.md b/docs/specification/README.md index d1faa18..e616117 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -702,6 +702,16 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] _Example 19. Code snippet for a Sensitive Overlay_ +#### Community Overlays + +Community overlays are task-specific objects which are integral part OCA Bundle. +Defined by the community can be used to extend functionality of [OCA +Bundle](#bundle). + +Community overlay needs to adhere to the OCA specification and MUST include +[Mandatory attributes](#mandatory-attributes) and MAY include [Common +attributes](#common-attributes) if necessary follwed by any overlay specific attributes. + ### Bundle An OCA Bundle is a set of OCA objects which MUST included a `Capture Base` and MAY consist of any number of `Overlays`. An encoded cryptographic digest of the contained objects produces a From 98de0db90abc487d493dc94d8325a024e7d46561 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Fri, 7 Feb 2025 10:44:00 +0100 Subject: [PATCH 29/46] feat: allow for community namespace in the type Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index e616117..c1bca8f 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -211,13 +211,16 @@ The `overlay` attribute contains the SAID of the [Overlay](#overlays) to cryptog The `type` attribute identifies the schema object type. The version aligns with the corresponding OCA specification version, ensuring that the object remains compatible with the specified OCA specification. ```abnf -type = "spec/overlay/" overlay_name "/" sem_ver -overlay_name = ALPHA +type = "("spec" / "community)/overlays/" overlay_name "/" sem_ver +overlay_name = namespace ":" ALPHA / ALPHA +namespace = ALPHA sem_ver = DIGIT "." DIGIT "." DIGIT ``` _Listing: ABNF core rules_ +`spec` should be used when the object is defined by core specification and `community` when it is community defined object. + #### Common attributes ##### Language From bfe4e56853f1803ea1fa8b7d943b2cb719f85e6b Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 16:13:02 +0100 Subject: [PATCH 30/46] chore: fix typos Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index c1bca8f..6b0c003 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -38,6 +38,7 @@ description: Official OCA specification Ryan Barrett (Stratosoft LLC) Robert Mitwicki ([ Human Colossus Foundation ](https://humancolossus.foundation/)) + Michal Pietrus ([ ArgonAUTHs ](https://argonauths.eu/)) Marcin Olichwiruk ([ ArgonAUTHs ](https://argonauths.eu/)) @@ -184,9 +185,6 @@ developing additional overlays as needed. This approach fosters a **dominant design** process, enabling the community to determine which **task-specific overlays** are most meaningful and valuable. See [Community overlays](#community-overlays) for more details. - - - #### Mandatory attributes Overlays are cryptographically-linked objects that provide layers of task-oriented definitional or contextual information to a other [OCA Objects](#oca-object-types). Any actor interacting with a published Capture Base can use Overlays to add metadata to the underlying object, transform how information is displayed to a viewer, or guide an agent in applying a custom process to captured data. @@ -707,7 +705,7 @@ _Example 19. Code snippet for a Sensitive Overlay_ #### Community Overlays -Community overlays are task-specific objects which are integral part OCA Bundle. +Community overlays are task-specific objects which are integral part of OCA Bundle. Defined by the community can be used to extend functionality of [OCA Bundle](#bundle). From 9a66aa363050464c2ec19a49bf8e3f89881765a2 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 16:17:31 +0100 Subject: [PATCH 31/46] chore: add link to eupl1.2 license Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 6b0c003..68cb622 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -50,7 +50,9 @@ description: Official OCA specification Copyrights:
- Human Colossus Foundation, EUPL v1.2 licence. + +Human Colossus Foundationi, [ EUPL v1.2 licence ](https://interoperable-europe.ec.europa.eu/collection/eupl/eupl-text-eupl-12). +
Governance: From d0cc8c39e954edff6348f2e58380b3bda5f36d98 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 18:27:37 +0100 Subject: [PATCH 32/46] feat: add d field to overlay Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/specification/README.md b/docs/specification/README.md index 68cb622..cfda178 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -193,6 +193,7 @@ Overlays are cryptographically-linked objects that provide layers of task-orient Overlays `MUST` consist of the following attributes in that order: +- `d` - deterministic identifier of the overlay - [ capture_base ](#capture-base-1) or [overlay](#overlay) - [ type ](#type-1) - Overlay-specific attributes From f6572dd6653e2c34202c0949fbd3d727d31fbdb2 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 18:28:19 +0100 Subject: [PATCH 33/46] feat: Add calculation of SAID and fix references Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 57 ++++++++++++++++++++++++++++++++---- 1 file changed, 51 insertions(+), 6 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index cfda178..5283dc5 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -201,11 +201,11 @@ Overlays `MUST` consist of the following attributes in that order: ##### Capture base -The `capture_base` attribute contains the SAID of the [Capture Base](#capture-base) to cryptographically anchor to that parent object. +The `capture_base` attribute contains the [SAID](#ref-SAID) of the [Capture Base](#capture-base) to cryptographically anchor to that parent object. ##### Overlay -The `overlay` attribute contains the SAID of the [Overlay](#overlays) to cryptographically anchor to that parent object. +The `overlay` attribute contains the [SAID](#ref-SAID) of the [Overlay](#overlays) to cryptographically anchor to that parent object. ##### Type @@ -499,7 +499,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), the Entry Code - a set of pre-defined entry keys for a nested series of key-value pairs; or - - a SAID that references a code table from an external data source to retrieve an array of pre-defined entry keys for a nested series of key-value pairs. See [Code Tables](#code-tables) for more information on code tables. + - a [SAID](#ref-SAID) that references a code table from an external data source to retrieve an array of pre-defined entry keys for a nested series of key-value pairs. See [Code Tables](#code-tables) for more information on code tables. ```json { @@ -532,7 +532,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), and [languag]( - a set of pre-defined values in a nested series of key-value pairs that are human-meaningful and language-dependent where the entry keys are taken from an associated Entry Code Overlay; or - - a SAID that references a code table from an external data source to retrieve an array of pre-defined values from a nested series of key-value pairs that are human-meaningful and language-dependent where the entry keys are taken from an associated Entry Code Overlay. See [Code Tables](#code-tables) for more information. + - a [SAID](#ref-SAID) that references a code table from an external data source to retrieve an array of pre-defined values from a nested series of key-value pairs that are human-meaningful and language-dependent where the entry keys are taken from an associated Entry Code Overlay. See [Code Tables](#code-tables) for more information. ```json { @@ -661,7 +661,7 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] - `code_table` - The `code_table` attribute contains a SAID that references an external code table. See [Code Tables](#code-tables) for more information. + The `code_table` attribute contains a [SAID](#ref-SAID) that references an external code table. See [Code Tables](#code-tables) for more information. - `attr_units` @@ -862,6 +862,40 @@ TODO update example ``` _Example 20. Code snippet for an OCA Bundle._ +### Deterministic Identifier + +Within the scope of the OCA specification, Deterministic Identifiers are always +Self-Addressing Identifiers ([SAIDs](#ref-SAID)). These identifiers are encoded +using Base64 URL-safe characters. For detailed information on their +functionality, please refer to the [SAID](#ref-SAID) specification. Below, we +distill the most relevant aspects of SAIDs in the context of the OCA +specification. + +#### How to calculate SAID: + +1. Convert the object ([bundle](#bundle) or [capture base](#capture-base) or [overlay](#overlays)) +into its canonical form, ensuring all whitespace is removed. +2. Replace the SAID field value in the serialization with a dummy string of the +same length as the chosen digest algorithm (e.g. BLAKE3-256 is 32 bytes, which +is 44 characters in Base64 URL-Safe). The dummy character is `#` (ASCII 35 in +decimal, 0x23 in hex). See [CESR](#ref-CESR) code tables for available algorithms. +3. Compute the digest of the modified serialization, which includes the dummy +SAID value. +4. Replace the dummy characters with the computed SAID value. + +#### How to verify object + +1. Convert the object ([bundle](#bundle) or [capture base](#capture-base) or [overlay](#overlays)) +into its canonical form, ensuring all whitespace is removed. +2. Replace the SAID field value in the serialization with a dummy string of the +same length as the digest algorithm. Use the digest algorithm specified by the +[CESR](#ref-CESR) derivation code of the copied SAID. The dummy character is # +(ASCII 35 in decimal, 0x23 in hex). +3. Compute the digest of the modified serialization, which includes the dummy +SAID value. Use the digest algorithm specified by the CESR derivation code of +the copied SAID. +4. Replace the dummy characters with the computed SAID value.` + ### Code Tables @@ -870,7 +904,7 @@ A code table is an external dataset structured as either: - an array of data; or - a map of key-value pairs. -A code table MUST be identifiable, verifiable, and resolvable by a SAID. +A code table MUST be identifiable, verifiable, and resolvable by a [SAID](#ref-SAID). #### Code Table for Keys @@ -999,6 +1033,17 @@ Smith, S. Self-Addressing IDentifier (SAID) (2022) [ https://datatracker.ietf.or +
+
+ [CESR] +
+
+ +Composable Event Streaming Representation (CESR) [ https://trustoverip.github.io/tswg-cesr-specification/](https://trustoverip.github.io/tswg-cesr-specification/) + +
+
+ ### Informative References
From f9fe56a67388a064146d86c37835e85e60b7af73 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 18:38:38 +0100 Subject: [PATCH 34/46] chore: Update governance to OCA WG Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 5283dc5..5930d84 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -59,7 +59,7 @@ Human Colossus Foundationi, [ EUPL v1.2 licence ](https://interoperable-europe.e
- The Decentralised Semantics Working Group maintains the OCA specification at [ Human Colossus Foundation ](https://humancolossus.foundation). Comments regarding this specification can be provided as issues on the official [ OCA Github ](https://github.com/the-human-colossus-foundation/oca-spec/issues). + The Overalays Capture Architecture (OCA) Working Group maintains the OCA specification at [ Human Colossus Foundation ](https://humancolossus.foundation). Comments regarding this specification can be provided as issues on the official [ OCA Github ](https://github.com/the-human-colossus-foundation/oca-spec/issues).
From 2b7aa6c31bf27b89f3cc0e5c9baa825689cbc4d9 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 19:04:29 +0100 Subject: [PATCH 35/46] chore: fix links and styling Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 46 +++++++++++++++++++++++++++--------- 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 5930d84..a1d8f4e 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -104,9 +104,9 @@ An `OCA object` is either a [Capture Base](#capture-base) or a task-specific [Ov A `Capture Base` is a base object that defines a single dataset in its purest form, providing a structural base to harmonise data. The object defines attribute names and types. -The Capture Base consists of the following attributes in that order: +The Capture Base comprises the following attributes, listed in order to form its canonical serialization: -- `d` - deterministic identifier of the capture base +- `d` - [deterministic identifier](#deterministic-identifier) of the capture base - [ type ](#type) - [ attributes ](#attributes) @@ -142,7 +142,7 @@ _Listing: ABNF core rules \[[RFC5234](#ref-RFC5234)\]_ #### Attributes -The "attributes" attribute maps key-value pairs where the key is the attribute name and the value is the attribute type. +The `attributes` attribute maps key-value pairs where the key is the attribute name and the value is the attribute type. ##### Attribute name @@ -165,13 +165,37 @@ _Listing: ABNF representation of the attribute name_ An attribute type determines the attribute's syntax and how attributes of that type are compared and sorted. A Capture Base recognises seven core data types: -- **Text**: a data type that defines a human-readable sequence of characters and the words they form, subsequently encoded into computer-readable formats such as ASCII \[[RFC0020](#ref-RFC0020)\]. -- **Numeric**: a data type that defines anything relating to or containing numbers. Examples of numeric data types include 8-byte integers, fixed precision and scale numeric data, floating precision number data, integer (whole number) data, and monetary data values. -- **Reference**: a data type that defines a Self-Addressing IDentifier (SAID) \[[SAID](#ref-SAID)\] that references a set of attributes through its associated parent. For example, the reference data type enables the development of nested data objects, where the organisation of information is in layers or where objects contain other similar objects. SAID is an identifier that is deterministically generated from and embedded in the content it identifies, making it and its data mutually tamper-evident. -- **Boolean**: a data type where the data only has two possible variables: true or false. In computer science, Boolean is an identification classifier for calculating logical truth values and algebraic variables. -- **Binary**: a data type that defines a binary code signal, a series of electrical pulses representing numbers, characters, and performed operations. Based on a binary number system, each digit position represents a power of two (e.g., 4, 8, 16, etc.). A set of four binary digits or bits in binary code represents each decimal number (0 to 9). Each digit has two possible states: off and on (usually symbolised by 0 and 1). Combining basic Boolean algebraic operations on binary numbers makes it possible to represent each of the four fundamental arithmetic operations of addition, subtraction, multiplication, and division. -- **DateTime**: a data type that defines the number of seconds or clock ticks that have elapsed since the defined epoch for that computer or platform. Common formats include dates (e.g., YYYY-MM-DD), times (e.g., hh:mm:ss), dates and times concatenated (e.g., `YYYY-MM-DDThh:mm:ss.sss+zz:zz`), and durations (e.g., `PnYnMnD`). -- **Array[data type]**: a data type that defines a structure that holds several data items or elements of the same data type. When you want to store many pieces of data that are related and have the same data type, it is often better to use an array instead of many separate variables (e.g., `Array[Text]`, `Array[Numeric]`, etc.). +- **Numeric**: a data type that defines anything relating to or containing +numbers. Examples of numeric data types include 8-byte integers, fixed precision +and scale numeric data, floating precision number data, integer (whole number) +data, and monetary data values. +- **Reference**: a data type that defines a Self-Addressing IDentifier +([SAID](#ref-SAID)) that references a set of attributes through its associated +parent. For example, the `reference` data type enables the development of nested +data objects, where the organisation of information is in layers or where +objects contain other similar objects. +- **Boolean**: a data type where the data only has two possible variables: true +or false. In computer science, Boolean is an identification classifier for +calculating logical truth values and algebraic variables. +- **Binary**: a data type that defines a binary code signal, a series of +electrical pulses representing numbers, characters, and performed operations. +Based on a binary number system, each digit position represents a power of two +(e.g., 4, 8, 16, etc.). A set of four binary digits or bits in binary code +represents each decimal number (0 to 9). Each digit has two possible states: off +and on (usually symbolised by 0 and 1). Combining basic Boolean algebraic +operations on binary numbers makes it possible to represent each of the four +fundamental arithmetic operations of addition, subtraction, multiplication, and +division. +- **DateTime**: a data type that defines the number of seconds or clock ticks +that have elapsed since the defined epoch for that computer or platform. Common +formats include dates (e.g., YYYY-MM-DD), times (e.g., hh:mm:ss), dates and +times concatenated (e.g., `YYYY-MM-DDThh:mm:ss.sss+zz:zz`), and durations (e.g., +`PnYnMnD`). +- **Array[data type]**: a data type that defines a structure that holds several +data items or elements of the same data type. When you want to store many pieces +of data that are related and have the same data type, it is often better to use +an array instead of many separate variables (e.g., `Array[Text]`, +`Array[Numeric]`, etc.). ### Overlays @@ -193,7 +217,7 @@ Overlays are cryptographically-linked objects that provide layers of task-orient Overlays `MUST` consist of the following attributes in that order: -- `d` - deterministic identifier of the overlay +- `d` - [deterministic identifier](#deterministic-identifier) of the overlay - [ capture_base ](#capture-base-1) or [overlay](#overlay) - [ type ](#type-1) - Overlay-specific attributes From 4235bf9a35faa71d079b1c4dba3720d495ec3cd9 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 19:07:37 +0100 Subject: [PATCH 36/46] Revert "feat: Use 639-3 for language codes" Keep country code and language code to cover most practical languages. This reverts commit 6fbbcbea320cd3d00b39dba93de1a69cad4804b3. Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 61 +++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 28 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index a1d8f4e..d93a819 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -253,28 +253,15 @@ _Listing: ABNF core rules_ To indicate language-specific information, some overlays would include a `language` attribute to indicate localization of that overlay. Those overlays are marked in the specification as `[lagnauge-specific object]` -The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has standardised comprehansive list of language-related codes called ISO 639-3. +The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has standardised two lists of language-related codes: the language codes called ISO 639-1 alpha-2 \[[ISO639](#ref-ISO639)\] codes ("Codes for the representation of names of languages") and ISO 3166-1 alpha-2 \[[ISO3166](#ref-ISO3166)\] codes ("Codes for the representation of names of countries"). Both consist of two letters. The language code is written in lowercase while the country code is written in uppercase. However, both ISO classifications may be combined to differentiate regional languages. -The `language` attribute MUST contain the three-letter language code (lowercase) according to the [ISO 639-3](#ref-ISO639). +The `language` attribute MUST contain either the two-letter language code (lowercase) for a national language or the combined language (lowercase)/country (uppercase) code for a regional language or locale. + +![Table 1](/images/spec-table1.png) +_Table 1. An example of ISO standard values for language and combined language/country codes._ -```json -{ - "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", - "type": "spec/overlays/label/1.0.2", - "language": "pol", - "attributes": { - "dateOfBirth": "Data urodzenia", - "documentNumber": "Numer paszportu", - "documentType": "Typ dokumentu", - "fullName": "Imię i nazwisko", - "height": "Wzrost", - "issuingState": "Wydający państwo", - "photoImage": "Zdjęcie" -} -``` -_Example: Code snipet of lable overlay with language attribute set to polish_ -#### Semantic Overlays +### Semantic Overlays Semantic overlays provide contextual meaning to describe objects and their relationships. ##### Character Encoding Overlay @@ -373,7 +360,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes) and [language]( { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/label/1.0.2", - "language": "eng", + "language": "en_UK", "attribute_labels": { "dateOfBirth": "Date of birth", "documentNumber": "Passport Number", @@ -411,14 +398,14 @@ and MAY include other attributes at the discretion of the overlay producer, such { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/meta/1.0.2", - "language": "eng", + "language": "en_UK", "name": "Digital Passport", "description": "An example of a Digital Passport schema", "affiliation": "The Government of Antarctica" } ``` -_Example 6. Code snippet for a Meta Overlay (language: en)._ +_Example 6. Code snippet for a Meta Overlay (language: en_UK)._ ##### Standard Overlay @@ -562,7 +549,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), and [languag]( { "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/entry/1.0.2", - "language": "eng", + "language": "en_UK", "attribute_entries": { "documentType": { "PE": "DIPLOMATIC PASSPORT", @@ -578,7 +565,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), and [languag]( } ``` -_Example 12. Code snippet for an Entry Overlay (language: en)._ +_Example 12. Code snippet for an Entry Overlay (language: en_UK)._ ##### Unit Overlay @@ -848,7 +835,7 @@ TODO update example "d": "EIBXpVvka3_4lheeajtitiafIP78Ig8LDMVX9dXpCC2l", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", "type": "spec/overlays/information/1.0", - "language": "eng", + "language": "en_UK", "attribute_information": { "d": "Schema digest", "i": "Credential Issuee", @@ -861,7 +848,7 @@ TODO update example "d": "ECZc26INzjxVbNo7-hln6xN3HW3e1r6NGDmA5ogRo6ef", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", "type": "spec/overlays/label/1.0", - "language": "eng", + "language": "en_UK", "attribute_categories": [], "attribute_labels": { "d": "Schema digest", @@ -876,7 +863,7 @@ TODO update example "d": "EOxvie-zslkGmFzVqYAzTVtO7RyFXAG8aCqE0OougnGV", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", "type": "spec/overlays/meta/1.0", - "language": "eng", + "language": "en_UK", "description": "Entrance credential", "name": "Entrance credential" } @@ -1195,7 +1182,25 @@ International Organization for Standardization (ISO) [https://www.iso.org/home.h
-ISO 639-1:2002, Codes for the representation of names of languages — Part 3 (2007) [https://www.iso.org/standard/74575.html](https://www.iso.org/standard/74575.html) +ISO 639-1:2002, Codes for the representation of names of languages — Part 1: Alpha-2 code (2019) [https://www.iso.org/standard/22109.html](https://www.iso.org/standard/22109.html) + +
+ +
+[ISO3166] +
+
+ +ISO 3166-1:2020, Codes for the representation of names of countries and their subdivisions — Part 1: Country code (2020) [https://www.iso.org/standard/72482.html](https://www.iso.org/standard/72482.html) + +
+ +
+[ISO7501] +
+
+ +ISO/IEC 7501-1:2008, Identification cards — Machine readable travel documents — Part 1: Machine-readable passport (2021) [https://www.iso.org/standard/45562.html](https://www.iso.org/standard/45562.html)
From f103747af9aa12e2c9cbf828b3cf0772b48556ec Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 19:20:42 +0100 Subject: [PATCH 37/46] chore: improve description of overlay canonical form Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index d93a819..dbbe780 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -215,12 +215,11 @@ overlays** are most meaningful and valuable. See [Community overlays](#community Overlays are cryptographically-linked objects that provide layers of task-oriented definitional or contextual information to a other [OCA Objects](#oca-object-types). Any actor interacting with a published Capture Base can use Overlays to add metadata to the underlying object, transform how information is displayed to a viewer, or guide an agent in applying a custom process to captured data. -Overlays `MUST` consist of the following attributes in that order: - +Overlays `MUST` comprises the following attributes, listed in order to form its canonical serialization: - `d` - [deterministic identifier](#deterministic-identifier) of the overlay - [ capture_base ](#capture-base-1) or [overlay](#overlay) - [ type ](#type-1) -- Overlay-specific attributes +- Overlay-specific attributes sorted in lexicographic order - See specific overlay types for more information. ##### Capture base From 54ad392a9cc0ce6e7380c3ffa457e65c711e8bf1 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 20:07:35 +0100 Subject: [PATCH 38/46] chore: update examples and fix styling Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 152 +++++++++++++++++++++-------------- 1 file changed, 92 insertions(+), 60 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index dbbe780..3b92337 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -299,6 +299,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), the Character ```json { + "d": "EPeH3AVhmGMLRT-DGqm6B9RY2q5-bC6ckTrFd__z6FYJ", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/character_encoding/1.0.2", "default_character_encoding": "utf-8", @@ -330,6 +331,7 @@ The inputted format values are dependent on the following core data types as def ```json { + "d": "EIpe9Ra0tUWTPFrZU-Jo_EufovDqrbFOgwc2YppvTvFD", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/format/1.0.2", "attribute_formats": { @@ -357,6 +359,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes) and [language]( ```json { + "d": "EPstaptvuTLvr6r2b0JBLzxaQzMZKkcKaYZBQTYPrdaL", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/label/1.0.2", "language": "en_UK", @@ -369,7 +372,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes) and [language]( "issuingState": "Issuing State or organization (in full)", "photoImage": "Portrait image", "sex": "Sex" - }, + } } ``` @@ -395,6 +398,7 @@ and MAY include other attributes at the discretion of the overlay producer, such ```json { + "d": "EGzJ1hFOPWD1J5Bq2TA-NR0ssPunJJO_7uxngJNDXcXs", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/meta/1.0.2", "language": "en_UK", @@ -420,6 +424,7 @@ There are many international standards organisations establishing tens of thousa ```json { + "d": "EMd8KksaUfkmfzzTJBx4gsTz0d8JaId3Lj4otsY9stXg", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/standard/1.0.2", "attr_standards": { @@ -455,6 +460,7 @@ Note that `n` and `m` are positive integers. ```json { + "d": "EMWxTY5PLoPOtyb-XgiB3BiRpqlHhxRTW7hqAI50UFsl", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/cardinality/1.0.2", "attr_cardinality": { @@ -477,6 +483,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), the Conformanc ```json { + "d": "EIP9FA6J_fvw0wjnvjPVQqkoYol627D-NdvkhptxfyDM", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/conformance/1.0.2", "attribute_conformance": { @@ -513,6 +520,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), the Entry Code ```json { + "d": "EPiSWiwDzZCVvXSSs2icINxtHC1_S7gKzhFylVz7iGw0", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/entry_code/1.0.2", "attribute_entry_codes": { @@ -546,6 +554,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), and [languag]( ```json { + "d": "EKnniFpc80_9VqcJjHnywYtHZEaq12d5i1Bo6Va6VAiZ", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/entry/1.0.2", "language": "en_UK", @@ -590,6 +599,7 @@ and MUST include the following attribute: ```json { + "d": "EC7S-U_CxSesNHEEZ6eZjT1TPxvsJsuND_EeTnbajfW4", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/unit/1.0.2", "metric_system": "SI", @@ -607,6 +617,7 @@ An Attribute Mapping Overlay defines attribute mappings between two distinct dat ```json { + "d": "EMlNpqhCrG1uGkr6arEAKK_K5VockXzoD6ljMT-nLfxZ", "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc", "type": "spec/overlays/mapping/1.0.2", "attribute_mapping": { @@ -624,6 +635,7 @@ An Entry Code Mapping Overlay defines the entry key mappings between two distinc ```json { + "d": "EBDUBwcC2pbACiGcTSVfGiYZktdl_SHUi7zJlSRSgABb", "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc", "type": "spec/overlays/entry_code_mapping/1.0.2", "attr_entry_codes_mapping": { @@ -637,7 +649,6 @@ An Entry Code Mapping Overlay defines the entry key mappings between two distinc "AIA:AI", "ATA:AQ", "ATG:AG", - "..." ] } } @@ -651,6 +662,7 @@ A Subset Overlay defines a customised version of a published schema containing a ```json { + "d": "ENyLjLiRetRlaDqcEASwMnk6jDKIx7ylXDB8GOfqc0d5", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/subset/1.0.2", "attributes": ["dateOfBirth", "documentNumber", "documentType"] @@ -661,7 +673,15 @@ _Example 16. Code snippet for a Subset Overlay._ ##### Unit Mapping Overlay -A Unit Mapping Overlay defines target units for quantitative data when converting between different units of measurement. Conversion of units is the conversion between different units of measurement for the same quantity, typically through multiplicative conversion factors (see [Code Table for Unit mappings](#code-table-for-unit-mappings) for more information on conversion factors) which change the measured quantity value without changing its effects. The process of conversion depends on the specific situation and the intended purpose. This may be governed by regulation, contract, technical specifications or other published standards. +A Unit Mapping Overlay defines target units for quantitative data when +converting between different units of measurement. Conversion of units is the +conversion between different units of measurement for the same quantity, +typically through multiplicative conversion factors (see [Code Table for Unit +mappings](#code-table-for-unit-mappings) for more information on conversion +factors) which change the measured quantity value without changing its effects. +The process of conversion depends on the specific situation and the intended +purpose. This may be governed by regulation, contract, technical specifications +or other published standards. In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Unit Mapping Overlay MUST include the following attributes: @@ -708,9 +728,10 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] ```json { + "d": "EKzY_KAP0U05dQ4_radjWu1TkbBFOh50wIgAEKTNP9R2", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/sensitive/1.0", - "attributes": ["sex"] + "attributes": ["first_name", "last_name"] } ``` @@ -726,10 +747,15 @@ Community overlay needs to adhere to the OCA specification and MUST include [Mandatory attributes](#mandatory-attributes) and MAY include [Common attributes](#common-attributes) if necessary follwed by any overlay specific attributes. +The **canonical form** of a **community overlay** follows the same rules as the +**canonical form** of the **core overlay**. + ### Bundle -An OCA Bundle is a set of OCA objects which MUST included a `Capture Base` and MAY consist of any number of `Overlays`. An encoded cryptographic digest of the contained objects produces a -deterministic identifier for the bundle. +An OCA Bundle is a set of OCA objects which MUST included a `Capture Base` and +MAY consist of any number of `Overlays`. An encoded cryptographic digest of the +contained objects produces a [deterministic +identifier](#deterministic-identifier) for the bundle. #### Canonical form @@ -761,11 +787,20 @@ OCAS_ Where: -- `OCAS`: A fixed prefix indicating "OCA Structure". This identifies the string as conforming to the OCA Specification's versioning scheme. -- ``: A single-digit integer (0-9) representing the major version of the specification. A change in the major version indicates backward-incompatible updates to the structure. -- ``: A single-digit integer (0-9) representing the minor version of the specification. A change in the minor version indicates backward-compatible updates. -- ``: A string denoting the serialization format of the bundle. Supported format is: `JSON`: JavaScript Object Notation -- ``: A six-digit, zero-padded integer representing the size of the object in hex notation, size of the object is calculated with `d` field with dummy characters the same lenght as the eventual derived value. The dummy character is #, that is, ASCII 35 decimal (23 hex). +- `OCAS`: A fixed prefix indicating "OCA Structure". This identifies the string +as conforming to the OCA Specification's versioning scheme. +- ``: A single-digit integer (0-9) representing the major version of the +specification. A change in the major version indicates backward-incompatible +updates to the structure. +- ``: A single-digit integer (0-9) representing the minor version of the +specification. A change in the minor version indicates backward-compatible +updates. +- ``: A string denoting the serialization format of the bundle. +Supported format is: `JSON`: JavaScript Object Notation +- ``: A six-digit, zero-padded integer representing the size of the object +in hex notation, size of the object is calculated with `d` field with dummy +characters the same lenght as the eventual derived value. The dummy character is +#, that is, ASCII 35 decimal (23 hex). - '_': A version string terminator. *Example*: @@ -792,7 +827,6 @@ Consumers of the OCA Specification must implement validation logic to ensure the Validation failure must result in the rejection of the bundle as non-compliant with the specification. *Example*: -TODO update example ``` { "bundle": { @@ -808,66 +842,58 @@ TODO update example }, "classification": "", }, - "overlays": { - "character_encoding": { - "d": "ED6Eio9KG2jHdFg3gXQpc0PX2xEI7aHnGDOpjU6VBfjs", - "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", - "type": "spec/overlays/character_encoding/1.0", - "attribute_character_encoding": { - "d": "utf-8", - "i": "utf-8", - "passed": "utf-8" - } + "overlays": [ + { + "d": "ECZc26INzjxVbNo7-hln6xN3HW3e1r6NGDmA5ogRo6ef", + "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", + "type": "spec/overlays/label/1.0", + "language": "en_UK", + "attribute_labels": { + "d": "Schema digest", + "i": "Credential Issuee", + "passed": "Passed" + }, }, - "conformance": { - "d": "EJSRe8DnLonKf6GVT_bC1QHoY0lQOG6-ldqxu7pqVCU8", - "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", - "type": "spec/overlays/conformance/1.0", - "attribute_conformance": { - "d": "M", - "i": "M", - "passed": "M" - } + { + "d": "ED6Eio9KG2jHdFg3gXQpc0PX2xEI7aHnGDOpjU6VBfjs", + "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", + "type": "spec/overlays/character_encoding/1.0", + "attribute_character_encoding": { + "d": "utf-8", + "i": "utf-8", + "passed": "utf-8" + } }, - "information": [ - { + { "d": "EIBXpVvka3_4lheeajtitiafIP78Ig8LDMVX9dXpCC2l", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", "type": "spec/overlays/information/1.0", "language": "en_UK", "attribute_information": { - "d": "Schema digest", - "i": "Credential Issuee", - "passed": "Enables or disables passing" + "d": "Schema digest", + "i": "Credential Issuee", + "passed": "Enables or disables passing" } - } - ], - "label": [ - { - "d": "ECZc26INzjxVbNo7-hln6xN3HW3e1r6NGDmA5ogRo6ef", + }, + { + "d": "EJSRe8DnLonKf6GVT_bC1QHoY0lQOG6-ldqxu7pqVCU8", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", - "type": "spec/overlays/label/1.0", - "language": "en_UK", - "attribute_categories": [], - "attribute_labels": { - "d": "Schema digest", - "i": "Credential Issuee", - "passed": "Passed" - }, - "category_labels": {} - } - ], - "meta": [ - { + "type": "spec/overlays/conformance/1.0", + "attribute_conformance": { + "d": "M", + "i": "M", + "passed": "M" + } + }, + { "d": "EOxvie-zslkGmFzVqYAzTVtO7RyFXAG8aCqE0OougnGV", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", "type": "spec/overlays/meta/1.0", "language": "en_UK", "description": "Entrance credential", "name": "Entrance credential" - } - ] - } + } + } ``` _Example 20. Code snippet for an OCA Bundle._ @@ -918,13 +944,18 @@ A code table MUST be identifiable, verifiable, and resolvable by a [SAID](#ref-S #### Code Table for Keys -A Code Table for Keys provides an anchor to a reusable dataset for a common purpose, such as a list of country codes. Therefore, this object MAY be a reference target in an Entry Code Overlay. See [Entry Code Overlay](#entry-code-overlay) for more information. +A Code Table for Keys provides an anchor to a reusable dataset for a common +purpose, such as a list of country codes. Therefore, this object MAY be a +reference target in an Entry Code Overlay. See [Entry Code +Overlay](#entry-code-overlay) for more information. A Code Table for Keys MUST include the following attribute: - `keys` - The `keys` attribute is an array of pre-defined entry keys for a nested series of key-value pairs. A key is a unique identifier that points to an associated value. + The `keys` attribute is an array of pre-defined entry keys for a nested series + of key-value pairs. A key is a unique identifier that points to an associated + value. ```json { @@ -957,7 +988,8 @@ _Example 22. Code snippet for a Code Table for Key-Value pairs, providing a mapp #### Code Table for Unit mappings -A Code Table for Unit mappings provides a mapping of input units to output units for quantitative data. +A Code Table for Unit mappings provides a mapping of input units to output units +for quantitative data. The unit conversion process consists of the following steps: From 6fa727620cc0a09702face0454e91cca051198bf Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 20:09:19 +0100 Subject: [PATCH 39/46] feat: move unit mapping to community overlay Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 106 ----------------------------------- 1 file changed, 106 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 3b92337..ac0cf28 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -671,46 +671,6 @@ A Subset Overlay defines a customised version of a published schema containing a _Example 16. Code snippet for a Subset Overlay._ -##### Unit Mapping Overlay - -A Unit Mapping Overlay defines target units for quantitative data when -converting between different units of measurement. Conversion of units is the -conversion between different units of measurement for the same quantity, -typically through multiplicative conversion factors (see [Code Table for Unit -mappings](#code-table-for-unit-mappings) for more information on conversion -factors) which change the measured quantity value without changing its effects. -The process of conversion depends on the specific situation and the intended -purpose. This may be governed by regulation, contract, technical specifications -or other published standards. - -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Unit Mapping Overlay MUST include the following attributes: - -- `metric_system` - - The `metric_system` attribute contains the acronym of the chosen system of units (a coherent system of units of measurement) used for defining attribute units. - -- `code_table` - - The `code_table` attribute contains a [SAID](#ref-SAID) that references an external code table. See [Code Tables](#code-tables) for more information. - -- `attr_units` - - The `attr_units` attribute maps key-value pairs where the key is the attribute name and the value is the desired unit of measurement. - -```json -{ - "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc", - "type": "spec/overlays/unit/1.0", - "metric_system": "SI", - "code_table": "E3YDLacdI1GSGWhHywzrb5B0hOL/9TYWBsUkXC8fA4EY", - "attr_units": { - "blood_glucose": "mg/dL" - } -} -``` - -_Example 17. Code snippet for a Unit Mapping Overlay._ - ##### Sensitive Overlay A Sensitive Overlay is a specialized construct used to identify and flag attributes that require protection against unauthorized or unwarranted disclosure. Attributes marked by a Sensitive Overlay typically include data subject to legal, ethical, or privacy-related considerations, including but not limited to Personally Identifiable Information (PII), Quasi-Identifiable Information (QII)) or proprietary information. @@ -986,72 +946,6 @@ A Code Table for Key-Value pairs MUST include the following attribute: _Example 22. Code snippet for a Code Table for Key-Value pairs, providing a mapping from, in this case, three-character to two-character ISO country codes._ -#### Code Table for Unit mappings - -A Code Table for Unit mappings provides a mapping of input units to output units -for quantitative data. - -The unit conversion process consists of the following steps: - -1. Read source unit. -1. Read target unit. -1. Convert source unit to target unit. - -Conversion between units is defined as follows: - -``` -Target unit = source unit * conversion factor + offset -``` - -Except when converting between temperature units, offset equals 0 in most cases. - -::: tip An example of Celsius to Kelvin conversion: - -1. Given 37 Celsius -2. Expect Kelvin -3. `37 * 1 + 273.15 = 310.15 K` - -::: - -::: tip An example of Celsius to Fahrenheit conversion: - -1. Given 37 Celsius -2. Expect Fahrenheit -3. `37 * 1.8 + 32 = 98.6 F` - -::: - -Implementers MAY find E.J. Roschke’s "Units and Unit Conversions" (2001) \[[ROS2001](#ref-ROS2001)\] a helpful resource for conversion factors. - -A Code Table for Unit mappings MUST include the following attribute: - -- `entries` - - The `entries` attribute is a map of key-value pairs, where the key denotes the conversion from source to target (e.g., `m->mm` or `deg_c->deg_f`) and the value contains the conversion factor and the offset. - - All units and unit prefixes follow the "Data Protocols Lightweight Standards and Patterns for Data" \[[BER2013](#ref-BER2013)\] proposal for describing units associated with numeric quantities. - -```json -{ - "entries": { - "m->mm": { - "cf": 1000 - }, - "m->yd": { - "cf": 1.0936133 - }, - "deg_c->deg_f": { - "cf": 1.8, - "o": 32 - } - } -} -``` - -_Example 23. Code snippet for a Code Table for Unit mappings._ - -Code Table for Unit mappings is in denormalised form, meaning that the conversion between units and unit prefixes is pre-defined for all standard unit conversions for maximum efficiency. - ## References ### Normative References From 852e689471c4b000f3847df4194a1b8c5c22c384 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sat, 8 Feb 2025 20:10:20 +0100 Subject: [PATCH 40/46] chore: remove empty section Signed-off-by: Robert Mitwicki --- docs/specification/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index ac0cf28..a70662b 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -1265,5 +1265,3 @@ United Nations. Sustainable Development Goals (SDGs) [https://sdgs.un.org/goals] - -## Appendices From 1aea1597ccc5d79299802abf77df73b80ba47465 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Sun, 9 Feb 2025 09:54:44 +0100 Subject: [PATCH 41/46] chore: fix section levels --- docs/specification/README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index a70662b..8df880a 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -435,11 +435,11 @@ There are many international standards organisations establishing tens of thousa _Example 7. Code snippet for a Standard Overlay._ -#### Inputs Overlays +### Inputs Overlays Inputs overlays provide predefined inputs for data attestations. -##### Cardinality Overlay +#### Cardinality Overlay A Cardinality Overlay defines the minimum and maximum number of values that an attribute can have. For a relationship, the cardinality interval specifies the minimum and maximum number of relationship targets. @@ -471,7 +471,7 @@ Note that `n` and `m` are positive integers. _Example 8. Code snippet for a Cardinality Overlay._ -##### Conformance Overlay +#### Conformance Overlay A Conformance Overlay indicates whether data entry for each attribute is mandatory or optional. @@ -501,7 +501,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), the Conformanc _Example 10. Code snippet for a Conformance Overlay._ -##### Entry Code Overlay +#### Entry Code Overlay An Entry Code Overlay defines the entry keys in a series of key-value pairs stored in a code table (also known as a "lookup table") or dataset. The key is a unique identifier that points to its associated value. @@ -533,7 +533,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), the Entry Code _Example 11. Code snippet for an Entry Code Overlay._ -##### Entry Overlay +#### Entry Overlay _[language-specific object]_ @@ -575,7 +575,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), and [languag]( _Example 12. Code snippet for an Entry Overlay (language: en_UK)._ -##### Unit Overlay +#### Unit Overlay A Unit Overlay defines the units of measurement adopted by convention or law, used as a standard for measuring the same kind of quantitative data. The RECOMMENDED system to use is the International System of Units (SI) \[[BIPM](#ref-BIPM)\], French Système International d’Unités, an international decimal system of weights and measures derived from and extending the metric system of units. @@ -611,7 +611,7 @@ and MUST include the following attribute: _Example 13. Code snippet for a Unit Overlay._ -##### Attribute Mapping Overlay +#### Attribute Mapping Overlay An Attribute Mapping Overlay defines attribute mappings between two distinct data models. Data mapping provides a preliminary step for data integration tasks, including data transformation or data mediation between a data source and a destination or consolidation of multiple databases into a single database and identifying redundant columns of data for consolidation or elimination. @@ -629,7 +629,7 @@ An Attribute Mapping Overlay defines attribute mappings between two distinct dat _Example 14. Code snippet for an Attribute Mapping Overlay._ -##### Entry Code Mapping Overlay +#### Entry Code Mapping Overlay An Entry Code Mapping Overlay defines the entry key mappings between two distinct code tables or datasets. @@ -656,7 +656,7 @@ An Entry Code Mapping Overlay defines the entry key mappings between two distinc _Example 15. Code snippet for an Entry Code Mapping Overlay._ -##### Subset Overlay +#### Subset Overlay A Subset Overlay defines a customised version of a published schema containing a subset of source attributes, including their properties, types, codes, and relationship dependencies required for the information exchange. @@ -671,7 +671,7 @@ A Subset Overlay defines a customised version of a published schema containing a _Example 16. Code snippet for a Subset Overlay._ -##### Sensitive Overlay +#### Sensitive Overlay A Sensitive Overlay is a specialized construct used to identify and flag attributes that require protection against unauthorized or unwarranted disclosure. Attributes marked by a Sensitive Overlay typically include data subject to legal, ethical, or privacy-related considerations, including but not limited to Personally Identifiable Information (PII), Quasi-Identifiable Information (QII)) or proprietary information. @@ -697,7 +697,7 @@ In addition to the `capture_base` and `type` attributes (see [Common attributes] _Example 19. Code snippet for a Sensitive Overlay_ -#### Community Overlays +### Community Overlays Community overlays are task-specific objects which are integral part of OCA Bundle. Defined by the community can be used to extend functionality of [OCA @@ -730,7 +730,7 @@ Objects. The serialization algorithm consists of the following rules: - `capture_base` - the `Capture Base` object defined as per section [Capture Base](#capture-base) - `overlays` - an array, containing all the overlays, sorted ASC by the `d` attribute -##### Bundle Version +#### Bundle Version To ensure proper versioning and identification of bundles within the OCA Specification, we define a standardized string format for the bundle version. @@ -867,7 +867,7 @@ functionality, please refer to the [SAID](#ref-SAID) specification. Below, we distill the most relevant aspects of SAIDs in the context of the OCA specification. -#### How to calculate SAID: +#### How to calculate SAID 1. Convert the object ([bundle](#bundle) or [capture base](#capture-base) or [overlay](#overlays)) into its canonical form, ensuring all whitespace is removed. From 7d27eba7c2cead29bb87b92a0f7b09e7dc3e80b4 Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 13 Feb 2025 13:16:34 +0100 Subject: [PATCH 42/46] chore: fix typo --- docs/specification/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 8df880a..464f832 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -94,7 +94,7 @@ A [Capture Base](#capture-base) is the purest and simplest form of a schema, def #### What are Overlays? -[Overlays](#overlays) are task-specific objects that provide cryptographically-bound layers of definitional or contextual metadata to a [Capture Base](#capture-base). Any actor interacting with a published [Capture Base](#capture-base) can use [Overlays](#overlays) to enrich meaning of the data, transform how inputted data and metadata are displayed to a viewer or guide an agent in applying a custom process to captured data. +[Overlays](#overlays) are task-specific objects that provide cryptographically-bound layers of definitional or contextual metadata to a [Capture Base](#capture-base). Any actor interacting with a published [Capture Base](#capture-base) can use [Overlays](#overlays) to enrich the meaning of the data, transform how inputted data and metadata are displayed to a viewer or guide an agent in applying a custom process to captured data. ## OCA object types From 4c204badc9c45afa4537255650ba337a8528f03e Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 13 Feb 2025 14:15:00 +0100 Subject: [PATCH 43/46] chore: wrap lines --- docs/specification/README.md | 384 ++++++++++++++++++++++++++--------- 1 file changed, 288 insertions(+), 96 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 464f832..2128585 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -74,9 +74,16 @@ Human Colossus Foundationi, [ EUPL v1.2 licence ](https://interoperable-europe.e ## Conventions and Definitions -Sections marked as non-normative, along with all authoring guidelines, diagrams, examples, and notes in this specification, are for informational purposes only and are not mandatory for compliance. All other sections of this specification are normative and define the required rules and standards that must be followed to ensure conformity with the OCA Specification. +Sections marked as non-normative, along with all authoring guidelines, diagrams, +examples, and notes in this specification, are for informational purposes only +and are not mandatory for compliance. All other sections of this specification +are normative and define the required rules and standards that must be followed +to ensure conformity with the OCA Specification. -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted when, and only when, they appear in all capitals, as described in RFC 2119 \[[RFC2119](#ref-RFC2119)\]. +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted when, and only when, they appear in all capitals, +as described in RFC 2119 \[[RFC2119](#ref-RFC2119)\]. ## Introduction @@ -84,27 +91,50 @@ _This section is non-normative._ ### How does OCA work? -OCA is based on the FAIR data principles \[[FAIR2016](#ref-FAIR2016)\], a set of guiding principles to make data findable, accessible, interoperable, and reusable, to enable scientific data management and stewardship, and to be relevant to all digital economy stakeholders. +OCA is based on the FAIR data principles \[[FAIR2016](#ref-FAIR2016)\], a set of +guiding principles to make data findable, accessible, interoperable, and +reusable, to enable scientific data management and stewardship, and to be +relevant to all digital economy stakeholders. -OCA represents transient objects (domain-agnostic) and persistent schemas (domain-specific) as multi-dimensional objects consisting of a stable capture base and interoperable overlays. By introducing overlays as linked task-specific objects within the schema stack, the architecture offers an optimal level of efficiency and interoperability in alignment with FAIR principles. +OCA represents transient objects (domain-agnostic) and persistent schemas +(domain-specific) as multi-dimensional objects consisting of a stable capture +base and interoperable overlays. By introducing overlays as linked task-specific +objects within the schema stack, the architecture offers an optimal level of +efficiency and interoperability in alignment with FAIR principles. #### What is a Capture Base? -A [Capture Base](#capture-base) is the purest and simplest form of a schema, defining the structural characteristics of a dataset. It is the foundational layer upon which to bind task-specific objects to enhance the meaning of inputted data. +A [Capture Base](#capture-base) is the purest and simplest form of a schema, +defining the structural characteristics of a dataset. It is the foundational +layer upon which to bind task-specific objects to enhance the meaning of +inputted data. #### What are Overlays? -[Overlays](#overlays) are task-specific objects that provide cryptographically-bound layers of definitional or contextual metadata to a [Capture Base](#capture-base). Any actor interacting with a published [Capture Base](#capture-base) can use [Overlays](#overlays) to enrich the meaning of the data, transform how inputted data and metadata are displayed to a viewer or guide an agent in applying a custom process to captured data. +[Overlays](#overlays) are task-specific objects that provide +cryptographically-bound layers of definitional or contextual metadata to a +[Capture Base](#capture-base). Any actor interacting with a published [Capture +Base](#capture-base) can use [Overlays](#overlays) to enrich the meaning of the +data, transform how inputted data and metadata are displayed to a viewer or +guide an agent in applying a custom process to captured data. ## OCA object types -An `OCA object` is either a [Capture Base](#capture-base) or a task-specific [Overlay](#overlays) with a deterministic relationship to a [Capture Base](#capture-base) or another [Overlay](#overlays). When amalgamated as a [Bundle](#bundle), OCA objects provide the necessary structural, definitional, and contextual information to determine the meaning of inputted data at the time of data capture. +An `OCA object` is either a [Capture Base](#capture-base) or a task-specific +[Overlay](#overlays) with a deterministic relationship to a [Capture +Base](#capture-base) or another [Overlay](#overlays). When amalgamated as a +[Bundle](#bundle), OCA objects provide the necessary structural, definitional, +and contextual information to determine the meaning of inputted data at the time +of data capture. ### Capture Base -A `Capture Base` is a base object that defines a single dataset in its purest form, providing a structural base to harmonise data. The object defines attribute names and types. +A `Capture Base` is a base object that defines a single dataset in its purest +form, providing a structural base to harmonise data. The object defines +attribute names and types. -The Capture Base comprises the following attributes, listed in order to form its canonical serialization: +The Capture Base comprises the following attributes, listed in order to form its +canonical serialization: - `d` - [deterministic identifier](#deterministic-identifier) of the capture base - [ type ](#type) @@ -131,7 +161,10 @@ _Example 1. Code snippet for a Capture Base._ #### Type -The `type` attribute specifies the schema object type and its associated version. The version aligns with the corresponding OCA specification version, ensuring that the schema object remains compatible with the specified OCA specification. +The `type` attribute specifies the schema object type and its associated +version. The version aligns with the corresponding OCA specification version, +ensuring that the schema object remains compatible with the specified OCA +specification. ```abnf type = "spec/capture_base/" sem_ver @@ -142,11 +175,15 @@ _Listing: ABNF core rules \[[RFC5234](#ref-RFC5234)\]_ #### Attributes -The `attributes` attribute maps key-value pairs where the key is the attribute name and the value is the attribute type. +The `attributes` attribute maps key-value pairs where the key is the attribute +name and the value is the attribute type. ##### Attribute name -An attribute name is a string that uniquely identifies an attribute within an OCA layer and is used to reference that attribute by other layers throughout the OCA bundle. The string can be any valid Unicode code point. +An attribute name is a string that uniquely identifies an attribute within an +OCA layer and is used to reference that attribute by other layers throughout the +OCA bundle. The string can be any valid Unicode code point. + Example of a valid attribute name: - `FullName` - `person/name/fullName` @@ -160,10 +197,10 @@ character = %x0000-10FFFF _Listing: ABNF representation of the attribute name_ - ##### Attribute type -An attribute type determines the attribute's syntax and how attributes of that type are compared and sorted. A Capture Base recognises seven core data types: +An attribute type determines the attribute's syntax and how attributes of that +type are compared and sorted. A Capture Base recognises seven core data types: - **Numeric**: a data type that defines anything relating to or containing numbers. Examples of numeric data types include 8-byte integers, fixed precision @@ -199,23 +236,35 @@ an array instead of many separate variables (e.g., `Array[Text]`, ### Overlays -`Overlay` as a task-specific object provides layers of definitional or contextual metadata. OCA specification recognize two core types of overlays: -- [Semantic overlays](#semantic-overlays) - provide contextual meaning to describe objects and their relationships. -- [Inputs overlays](#inputs-overlays) - provide predefined inputs for data attestations. +`Overlay` as a task-specific object provides layers of definitional or +contextual metadata. OCA specification recognize two core types of overlays: +- [Semantic overlays](#semantic-overlays) - provide contextual meaning to +describe objects and their relationships. +- [Inputs overlays](#inputs-overlays) - provide predefined inputs for data +attestations. -In the context of this specification, these are considered **core overlays**, which, through **community consensus**, are deemed the most essential for inclusion and are among the most commonly used. +In the context of this specification, these are considered **core overlays**, +which, through **community consensus**, are deemed the most essential for +inclusion and are among the most commonly used. The **OCA Specification** intentionally limits the number of **predefined core overlays** to a **minimum**, allowing the community to take the lead in developing additional overlays as needed. This approach fosters a **dominant design** process, enabling the community to determine which **task-specific -overlays** are most meaningful and valuable. See [Community overlays](#community-overlays) for more details. +overlays** are most meaningful and valuable. See [Community +overlays](#community-overlays) for more details. #### Mandatory attributes -Overlays are cryptographically-linked objects that provide layers of task-oriented definitional or contextual information to a other [OCA Objects](#oca-object-types). Any actor interacting with a published Capture Base can use Overlays to add metadata to the underlying object, transform how information is displayed to a viewer, or guide an agent in applying a custom process to captured data. +Overlays are cryptographically-linked objects that provide layers of +task-oriented definitional or contextual information to a other [OCA +Objects](#oca-object-types). Any actor interacting with a published Capture Base +can use Overlays to add metadata to the underlying object, transform how +information is displayed to a viewer, or guide an agent in applying a custom +process to captured data. -Overlays `MUST` comprises the following attributes, listed in order to form its canonical serialization: +Overlays `MUST` comprises the following attributes, listed in order to form its +canonical serialization: - `d` - [deterministic identifier](#deterministic-identifier) of the overlay - [ capture_base ](#capture-base-1) or [overlay](#overlay) - [ type ](#type-1) @@ -224,15 +273,19 @@ Overlays `MUST` comprises the following attributes, listed in order to form its ##### Capture base -The `capture_base` attribute contains the [SAID](#ref-SAID) of the [Capture Base](#capture-base) to cryptographically anchor to that parent object. +The `capture_base` attribute contains the [SAID](#ref-SAID) of the [Capture +Base](#capture-base) to cryptographically anchor to that parent object. ##### Overlay -The `overlay` attribute contains the [SAID](#ref-SAID) of the [Overlay](#overlays) to cryptographically anchor to that parent object. +The `overlay` attribute contains the [SAID](#ref-SAID) of the +[Overlay](#overlays) to cryptographically anchor to that parent object. ##### Type -The `type` attribute identifies the schema object type. The version aligns with the corresponding OCA specification version, ensuring that the object remains compatible with the specified OCA specification. +The `type` attribute identifies the schema object type. The version aligns with +the corresponding OCA specification version, ensuring that the object remains +compatible with the specified OCA specification. ```abnf type = "("spec" / "community)/overlays/" overlay_name "/" sem_ver @@ -243,45 +296,75 @@ sem_ver = DIGIT "." DIGIT "." DIGIT _Listing: ABNF core rules_ -`spec` should be used when the object is defined by core specification and `community` when it is community defined object. +`spec` should be used when the object is defined by core specification and +`community` when it is community defined object. #### Common attributes ##### Language -To indicate language-specific information, some overlays would include a `language` attribute to indicate localization of that overlay. -Those overlays are marked in the specification as `[lagnauge-specific object]` +To indicate language-specific information, some overlays would include a +`language` attribute to indicate localization of that overlay. Those overlays +are marked in the specification as `[lagnauge-specific object]` -The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has standardised two lists of language-related codes: the language codes called ISO 639-1 alpha-2 \[[ISO639](#ref-ISO639)\] codes ("Codes for the representation of names of languages") and ISO 3166-1 alpha-2 \[[ISO3166](#ref-ISO3166)\] codes ("Codes for the representation of names of countries"). Both consist of two letters. The language code is written in lowercase while the country code is written in uppercase. However, both ISO classifications may be combined to differentiate regional languages. +The International Organization for Standardization (ISO) \[[ISO](#ref-ISO)\] has +standardised two lists of language-related codes: the language codes called ISO +639-1 alpha-2 \[[ISO639](#ref-ISO639)\] codes ("Codes for the representation of +names of languages") and ISO 3166-1 alpha-2 \[[ISO3166](#ref-ISO3166)\] codes +("Codes for the representation of names of countries"). Both consist of two +letters. The language code is written in lowercase while the country code is +written in uppercase. However, both ISO classifications may be combined to +differentiate regional languages. -The `language` attribute MUST contain either the two-letter language code (lowercase) for a national language or the combined language (lowercase)/country (uppercase) code for a regional language or locale. +The `language` attribute MUST contain either the two-letter language code +(lowercase) for a national language or the combined language (lowercase)/country +(uppercase) code for a regional language or locale. ![Table 1](/images/spec-table1.png) _Table 1. An example of ISO standard values for language and combined language/country codes._ ### Semantic Overlays -Semantic overlays provide contextual meaning to describe objects and their relationships. +Semantic overlays provide contextual meaning to describe objects and their +relationships. ##### Character Encoding Overlay -A Character Encoding Overlay defines the process of assigning numbers to graphical characters, especially the written characters of human language, allowing them to be stored, transmitted, and transformed using digital computers. Character encoding using internationally accepted standards permits worldwide interchange of text in electronic form. +A Character Encoding Overlay defines the process of assigning numbers to +graphical characters, especially the written characters of human language, +allowing them to be stored, transmitted, and transformed using digital +computers. Character encoding using internationally accepted standards permits +worldwide interchange of text in electronic form. -In addition to the [Mandatory attributes](#mandatory-attributes), the Character Encoding Overlay MUST include at least one of the following attributes: +In addition to the [Mandatory attributes](#mandatory-attributes), the Character +Encoding Overlay MUST include at least one of the following attributes: - `default_character_encoding` - The "default_character_encoding" attribute specifies the default character encoding for the attributes contained in the parent Capture Base. + The "default_character_encoding" attribute specifies the default character + encoding for the attributes contained in the parent Capture Base. - The most common default character set is UTF-8 \[[RFC3629](#ref-RFC3629)\], which accounts for 98% of all web pages in the World Wide Web and up to 100.0% for some languages, as of 2021. + The most common default character set is UTF-8 \[[RFC3629](#ref-RFC3629)\], + which accounts for 98% of all web pages in the World Wide Web and up to 100.0% + for some languages, as of 2021. - `attr_character_encoding` - The `attr_character_encoding` attribute maps key-value pairs where the key is the attribute name and the value is the character encoding. + The `attr_character_encoding` attribute maps key-value pairs where the key is + the attribute name and the value is the character encoding. - Any attributes contained in the `attr_character_encoding` attribute override the behaviour of the `default_character_encoding` attribute. + Any attributes contained in the `attr_character_encoding` attribute override + the behaviour of the `default_character_encoding` attribute. - There are many encoding standards including Base64 \[[RFC4648](#ref-RFC4648)\], UTF-8, and ASCII to name a few. Each standard has a purpose, and applications using those encoding standards expect to receive data compliant with that encoding standard. The most popular types of character encoding are ASCII and Unicode \[[UNICODE](#ref-UNICODE)\]. While ASCII is still supported by nearly all text editors, Unicode is more commonly used because it supports a larger character set. Unicode is often defined as UTF-8, UTF-16 \[[RFC2781](#ref-RFC2781)\], or UTF-32 \[[ISO10646](#ref-ISO10646)\], which refer to different Unicode standards. + There are many encoding standards including Base64 + \[[RFC4648](#ref-RFC4648)\], UTF-8, and ASCII to name a few. Each standard has + a purpose, and applications using those encoding standards expect to receive + data compliant with that encoding standard. The most popular types of + character encoding are ASCII and Unicode \[[UNICODE](#ref-UNICODE)\]. While + ASCII is still supported by nearly all text editors, Unicode is more commonly + used because it supports a larger character set. Unicode is often defined as + UTF-8, UTF-16 \[[RFC2781](#ref-RFC2781)\], or UTF-32 + \[[ISO10646](#ref-ISO10646)\], which refer to different Unicode standards. :::tip An example of character encoding for a text format: Data type: `Text`
@@ -313,21 +396,32 @@ In addition to the [Mandatory attributes](#mandatory-attributes), the Character ##### Format Overlay -A Format Overlay defines an input and display format for data fields. The data format enables conversion of the input buffer to the program variable and displays program variable data to form fields. +A Format Overlay defines an input and display format for data fields. The data +format enables conversion of the input buffer to the program variable and +displays program variable data to form fields. -In addition to the [Mandatory attributes](#mandatory-attributes), the Format Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Format +Overlay MUST include the following attribute: - `attribute_formats` - The "attribute_formats" attribute maps key-value pairs where the key is the attribute name and the value is the format. + The "attribute_formats" attribute maps key-value pairs where the key is the + attribute name and the value is the format. -The inputted format values are dependent on the following core data types as defined by the attribute types in the Capture Base: +The inputted format values are dependent on the following core data types as +defined by the attribute types in the Capture Base: -- **Text**: The inputted format value for this core data type MAY be a regular expression [REGEX], a sequence of characters that specifies a search pattern in text. +- **Text**: The inputted format value for this core data type MAY be a regular +expression [REGEX], a sequence of characters that specifies a search pattern in +text. -- **Binary**: The inputted format value for this core data type MAY be a MIME type registered with the Internet Assigned Numbers Authority (IANA) \[[IANA](#ref-IANA)\] +- **Binary**: The inputted format value for this core data type MAY be a MIME +type registered with the Internet Assigned Numbers Authority (IANA) +\[[IANA](#ref-IANA)\] -- **DateTime**: The inputted format value for this core data type MAY be a date and time representation as defined by ISO 8601, a standard for the worldwide exchange and communication of date and time-related data. +- **DateTime**: The inputted format value for this core data type MAY be a date +and time representation as defined by ISO 8601, a standard for the worldwide +exchange and communication of date and time-related data. ```json { @@ -349,13 +443,18 @@ _Example 3. Code snippet for a Format Overlay._ _[language-specific object]_ -A Label Overlay defines human readable attribute names. For example, for an attribute named `dateOfBirth`, you may wish to call it `Date of birth`, which is more meaningful and user-friendly when inspected by human. +A Label Overlay defines human readable attribute names. For example, for an +attribute named `dateOfBirth`, you may wish to call it `Date of birth`, which is +more meaningful and user-friendly when inspected by human. -In addition to the [Mandatory attributes](#mandatory-attributes) and [language](#language), the Label Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes) and +[language](#language), the Label Overlay MUST include the following attribute: - `attribute_labels` - The `attribute_labels` attribute maps key-value pairs where the key is the attribute name and the value is a human-meaningful attribute label in a specific language. + The `attribute_labels` attribute maps key-value pairs where the key is the + attribute name and the value is a human-meaningful attribute label in a + specific language. ```json { @@ -382,9 +481,12 @@ _Example 5. Code snippet for a Label Overlay (language: en)._ _[language-specific object]_ -A Meta Overlay defines any language-specific information about a schema. It is used for discovery and identification and includes elements such as the schema name and description. +A Meta Overlay defines any language-specific information about a schema. It is +used for discovery and identification and includes elements such as the schema +name and description. -In addition to the [Mandatory attributes](#mandatory-attributes) and [language](#language), the Meta Overlay SHOULD include the following attributes: +In addition to the [Mandatory attributes](#mandatory-attributes) and +[language](#language), the Meta Overlay SHOULD include the following attributes: - `name` @@ -394,7 +496,10 @@ In addition to the [Mandatory attributes](#mandatory-attributes) and [language]( The `description` attribute contains a description of the schema in a specific language. -and MAY include other attributes at the discretion of the overlay producer, such as an "affiliation" attribute in the example below. How the overlay producer conveys the purpose of the additional attributes in the Meta Overlay is outside the scope of this specification. +and MAY include other attributes at the discretion of the overlay producer, such +as an "affiliation" attribute in the example below. How the overlay producer +conveys the purpose of the additional attributes in the Meta Overlay is outside +the scope of this specification. ```json { @@ -412,15 +517,25 @@ _Example 6. Code snippet for a Meta Overlay (language: en_UK)._ ##### Standard Overlay -A Standard Overlay defines a documented agreement or technical specification published by a standards organisation used to represent, format, define, structure, tag, transmit, manipulate, use, and manage data. +A Standard Overlay defines a documented agreement or technical specification +published by a standards organisation used to represent, format, define, +structure, tag, transmit, manipulate, use, and manage data. -In addition to the [Mandatory attributes](#mandatory-attributes), the Standard Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Standard +Overlay MUST include the following attribute: - `attr_standards` - The `attr_standards` attribute maps key-value pairs where the key is the attribute name and the value is the standard. + The `attr_standards` attribute maps key-value pairs where the key is the + attribute name and the value is the standard. -There are many international standards organisations establishing tens of thousands of standards covering almost every conceivable topic. The three largest and most well-established standards organisations are the International Organization for Standardization (ISO), the International Electrotechnical Commission (IEC) \[[IEC](#ref-IEC)\], and the International Telecommunication Union (ITU) \[[ITU](#ref-ITU)\]. Standards tend to contain the acronym of the standards organisation followed by an internal document identifier. +There are many international standards organisations establishing tens of +thousands of standards covering almost every conceivable topic. The three +largest and most well-established standards organisations are the International +Organization for Standardization (ISO), the International Electrotechnical +Commission (IEC) \[[IEC](#ref-IEC)\], and the International Telecommunication +Union (ITU) \[[ITU](#ref-ITU)\]. Standards tend to contain the acronym of the +standards organisation followed by an internal document identifier. ```json { @@ -441,13 +556,17 @@ Inputs overlays provide predefined inputs for data attestations. #### Cardinality Overlay -A Cardinality Overlay defines the minimum and maximum number of values that an attribute can have. For a relationship, the cardinality interval specifies the minimum and maximum number of relationship targets. +A Cardinality Overlay defines the minimum and maximum number of values that an +attribute can have. For a relationship, the cardinality interval specifies the +minimum and maximum number of relationship targets. -In addition to the [Mandatory attributes](#mandatory-attributes), the Cardinality Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the +Cardinality Overlay MUST include the following attribute: - `attr_cardinality` - The `attr_cardinality` attribute maps key-value pairs where the key is the attribute name and the value is the cardinality interval. + The `attr_cardinality` attribute maps key-value pairs where the key is the + attribute name and the value is the cardinality interval. The logic of cardinality intervals is as follows: @@ -473,13 +592,17 @@ _Example 8. Code snippet for a Cardinality Overlay._ #### Conformance Overlay -A Conformance Overlay indicates whether data entry for each attribute is mandatory or optional. +A Conformance Overlay indicates whether data entry for each attribute is +mandatory or optional. -In addition to the [Mandatory attributes](#mandatory-attributes), the Conformance Overlay MAY include the following attributes: +In addition to the [Mandatory attributes](#mandatory-attributes), the +Conformance Overlay MAY include the following attributes: - `attribute_conformance ` - The `attribute_conformance` attribute maps key-value pairs where the key is the attribute name and the value is the data entry conformance of the attribute, which is set to either `M` (mandatory) or `O` (optional). + The `attribute_conformance` attribute maps key-value pairs where the key is + the attribute name and the value is the data entry conformance of the + attribute, which is set to either `M` (mandatory) or `O` (optional). ```json { @@ -503,20 +626,31 @@ _Example 10. Code snippet for a Conformance Overlay._ #### Entry Code Overlay -An Entry Code Overlay defines the entry keys in a series of key-value pairs stored in a code table (also known as a "lookup table") or dataset. The key is a unique identifier that points to its associated value. +An Entry Code Overlay defines the entry keys in a series of key-value pairs +stored in a code table (also known as a "lookup table") or dataset. The key is a +unique identifier that points to its associated value. ![Table 2](/images/spec-table2.png) -_Table 2. An example of how the values in an array of key-value pairs provided by an Entry Code Overlay subsequently define a set of pre-defined entry keys in a nested series of key-value pairs. The specified values are often standardised categorisation codes, valuable data inputs for statistical analysis, machine learning (ML), and artificial intelligence (AI) algorithms._ +_Table 2. An example of how the values in an array of key-value pairs provided +by an Entry Code Overlay subsequently define a set of pre-defined entry keys in +a nested series of key-value pairs. The specified values are often standardised +categorisation codes, valuable data inputs for statistical analysis, machine +learning (ML), and artificial intelligence (AI) algorithms._ -In addition to the [Mandatory attributes](#mandatory-attributes), the Entry Code Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Entry Code +Overlay MUST include the following attribute: - `attribute_entry_codes ` - The `attribute_entry_codes` attribute maps key-value pairs where the key is the attribute name and the value is either: + The `attribute_entry_codes` attribute maps key-value pairs where the key is + the attribute name and the value is either: - a set of pre-defined entry keys for a nested series of key-value pairs; or - - a [SAID](#ref-SAID) that references a code table from an external data source to retrieve an array of pre-defined entry keys for a nested series of key-value pairs. See [Code Tables](#code-tables) for more information on code tables. + - a [SAID](#ref-SAID) that references a code table from an external data + source to retrieve an array of pre-defined entry keys for a nested series of + key-value pairs. See [Code Tables](#code-tables) for more information on code + tables. ```json { @@ -537,20 +671,33 @@ _Example 11. Code snippet for an Entry Code Overlay._ _[language-specific object]_ -An Entry Overlay defines the entry values in a series of key-value pairs stored in a code table (also known as a "lookup table") or dataset. A value is either the identified data or a pointer to that data. +An Entry Overlay defines the entry values in a series of key-value pairs stored +in a code table (also known as a "lookup table") or dataset. A value is either +the identified data or a pointer to that data. ![Table 3](/images/spec-table3.png) -_Table 3. An example of how an Entry Overlay can leverage a set of pre-defined entry keys in a nested series of key-value pairs provided by an Entry Code Overlay to provide human-meaningful values in a specified national or regional language._ +_Table 3. An example of how an Entry Overlay can leverage a set of pre-defined +entry keys in a nested series of key-value pairs provided by an Entry Code +Overlay to provide human-meaningful values in a specified national or regional +language._ -In addition to the [Mandatory attributes](#mandatory-attributes), and [languag](#language), the Entry Overlay MUST include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), and +[languag](#language), the Entry Overlay MUST include the following attribute: - `attribute_entries` - The `attribute_entries` attribute maps key-value pairs where the key is the attribute name and the value is either: + The `attribute_entries` attribute maps key-value pairs where the key is the + attribute name and the value is either: - - a set of pre-defined values in a nested series of key-value pairs that are human-meaningful and language-dependent where the entry keys are taken from an associated Entry Code Overlay; or + - a set of pre-defined values in a nested series of key-value pairs that are + human-meaningful and language-dependent where the entry keys are taken from an + associated Entry Code Overlay; or - - a [SAID](#ref-SAID) that references a code table from an external data source to retrieve an array of pre-defined values from a nested series of key-value pairs that are human-meaningful and language-dependent where the entry keys are taken from an associated Entry Code Overlay. See [Code Tables](#code-tables) for more information. + - a [SAID](#ref-SAID) that references a code table from an external data + source to retrieve an array of pre-defined values from a nested series of + key-value pairs that are human-meaningful and language-dependent where the + entry keys are taken from an associated Entry Code Overlay. See [Code + Tables](#code-tables) for more information. ```json { @@ -577,25 +724,38 @@ _Example 12. Code snippet for an Entry Overlay (language: en_UK)._ #### Unit Overlay -A Unit Overlay defines the units of measurement adopted by convention or law, used as a standard for measuring the same kind of quantitative data. The RECOMMENDED system to use is the International System of Units (SI) \[[BIPM](#ref-BIPM)\], French Système International d’Unités, an international decimal system of weights and measures derived from and extending the metric system of units. +A Unit Overlay defines the units of measurement adopted by convention or law, +used as a standard for measuring the same kind of quantitative data. The +RECOMMENDED system to use is the International System of Units (SI) +\[[BIPM](#ref-BIPM)\], French Système International d’Unités, an international +decimal system of weights and measures derived from and extending the metric +system of units. -Adopted by the 11th General Conference on Weights and Measures (CGPM) in 1960, it is abbreviated SI in all languages. To date, the SI comprises seven base units: the meter (m), the kilogram (kg), the second (s), the ampere (A), the kelvin (K), the candela (cd) and the mole (mol). +Adopted by the 11th General Conference on Weights and Measures (CGPM) in 1960, +it is abbreviated SI in all languages. To date, the SI comprises seven base +units: the meter (m), the kilogram (kg), the second (s), the ampere (A), the +kelvin (K), the candela (cd) and the mole (mol). ![Fig 3](/images/spec-fig3.png) _Figure 3. The seven defining constants of the SI._ -In addition to the [Mandatory attributes](#mandatory-attributes), the Unit Overlay SHOULD include the following attribute: +In addition to the [Mandatory attributes](#mandatory-attributes), the Unit +Overlay SHOULD include the following attribute: - `metric_system` - The `metric_system` attribute contains the acronym of the chosen system of units (a coherent system of units of measurement) used for defining attribute units. + The `metric_system` attribute contains the acronym of the chosen system of + units (a coherent system of units of measurement) used for defining attribute + units. and MUST include the following attribute: - `attribute_units` - The `attribute_units` attribute maps key-value pairs where the key is the attribute name and the value is a standard unit of measurement from a known metric system. + The `attribute_units` attribute maps key-value pairs where the key is the + attribute name and the value is a standard unit of measurement from a known + metric system. ```json { @@ -613,7 +773,11 @@ _Example 13. Code snippet for a Unit Overlay._ #### Attribute Mapping Overlay -An Attribute Mapping Overlay defines attribute mappings between two distinct data models. Data mapping provides a preliminary step for data integration tasks, including data transformation or data mediation between a data source and a destination or consolidation of multiple databases into a single database and identifying redundant columns of data for consolidation or elimination. +An Attribute Mapping Overlay defines attribute mappings between two distinct +data models. Data mapping provides a preliminary step for data integration +tasks, including data transformation or data mediation between a data source and +a destination or consolidation of multiple databases into a single database and +identifying redundant columns of data for consolidation or elimination. ```json { @@ -631,7 +795,8 @@ _Example 14. Code snippet for an Attribute Mapping Overlay._ #### Entry Code Mapping Overlay -An Entry Code Mapping Overlay defines the entry key mappings between two distinct code tables or datasets. +An Entry Code Mapping Overlay defines the entry key mappings between two +distinct code tables or datasets. ```json { @@ -658,7 +823,9 @@ _Example 15. Code snippet for an Entry Code Mapping Overlay._ #### Subset Overlay -A Subset Overlay defines a customised version of a published schema containing a subset of source attributes, including their properties, types, codes, and relationship dependencies required for the information exchange. +A Subset Overlay defines a customised version of a published schema containing a +subset of source attributes, including their properties, types, codes, and +relationship dependencies required for the information exchange. ```json { @@ -673,14 +840,30 @@ _Example 16. Code snippet for a Subset Overlay._ #### Sensitive Overlay -A Sensitive Overlay is a specialized construct used to identify and flag attributes that require protection against unauthorized or unwarranted disclosure. Attributes marked by a Sensitive Overlay typically include data subject to legal, ethical, or privacy-related considerations, including but not limited to Personally Identifiable Information (PII), Quasi-Identifiable Information (QII)) or proprietary information. +A Sensitive Overlay is a specialized construct used to identify and flag +attributes that require protection against unauthorized or unwarranted +disclosure. Attributes marked by a Sensitive Overlay typically include data +subject to legal, ethical, or privacy-related considerations, including but not +limited to Personally Identifiable Information (PII), Quasi-Identifiable +Information (QII)) or proprietary information. -Sensitive Overlays are integral to ensuring compliance with legal and ethical standards while supporting robust data governance. Implementers must incorporate mechanisms to respect and enforce the protections designated by these overlays to maintain conformity with the OCA Specification. +Sensitive Overlays are integral to ensuring compliance with legal and ethical +standards while supporting robust data governance. Implementers must incorporate +mechanisms to respect and enforce the protections designated by these overlays +to maintain conformity with the OCA Specification. -The Blinding Identity Taxonomy (BIT) [KAN2020](#ref-KAN2020) is a practical tool for any practitioner whose organisation has custody or control of a dataset containing identifiable information about entities, including a natural person, organisation, or device with signing capabilities that make that entity uniquely identifiable. For example, data protection officers and schema issuers can use the BIT to flag a list of elements which require cryptographic encoding to reduce the risk of identifying a data principal. +The Blinding Identity Taxonomy (BIT) [KAN2020](#ref-KAN2020) is a practical tool +for any practitioner whose organisation has custody or control of a dataset +containing identifiable information about entities, including a natural person, +organisation, or device with signing capabilities that make that entity uniquely +identifiable. For example, data protection officers and schema issuers can use +the BIT to flag a list of elements which require cryptographic encoding to +reduce the risk of identifying a data principal. -In addition to the `capture_base` and `type` attributes (see [Common attributes](#common-attributes)), the Sensitive Overlay MUST include the following attribute: +In addition to the `capture_base` and `type` attributes (see [Common +attributes](#common-attributes)), the Sensitive Overlay MUST include the +following attribute: - `attributes` @@ -699,13 +882,14 @@ _Example 19. Code snippet for a Sensitive Overlay_ ### Community Overlays -Community overlays are task-specific objects which are integral part of OCA Bundle. -Defined by the community can be used to extend functionality of [OCA +Community overlays are task-specific objects which are integral part of OCA +Bundle. Defined by the community can be used to extend functionality of [OCA Bundle](#bundle). Community overlay needs to adhere to the OCA specification and MUST include [Mandatory attributes](#mandatory-attributes) and MAY include [Common -attributes](#common-attributes) if necessary follwed by any overlay specific attributes. +attributes](#common-attributes) if necessary follwed by any overlay specific +attributes. The **canonical form** of a **community overlay** follows the same rules as the **canonical form** of the **core overlay**. @@ -779,12 +963,14 @@ This indicates: *Validation* -Consumers of the OCA Specification must implement validation logic to ensure the bundle version string: +Consumers of the OCA Specification must implement validation logic to ensure the +bundle version string: - Matches the defined format and structure. - Uses only supported serialization formats. - Accurately represents the object's size in base64 encoding. -Validation failure must result in the rejection of the bundle as non-compliant with the specification. +Validation failure must result in the rejection of the bundle as non-compliant +with the specification. *Example*: ``` @@ -869,20 +1055,23 @@ specification. #### How to calculate SAID -1. Convert the object ([bundle](#bundle) or [capture base](#capture-base) or [overlay](#overlays)) -into its canonical form, ensuring all whitespace is removed. +1. Convert the object ([bundle](#bundle) or [capture base](#capture-base) or +[overlay](#overlays)) into its canonical form, ensuring all whitespace is +removed. 2. Replace the SAID field value in the serialization with a dummy string of the same length as the chosen digest algorithm (e.g. BLAKE3-256 is 32 bytes, which is 44 characters in Base64 URL-Safe). The dummy character is `#` (ASCII 35 in -decimal, 0x23 in hex). See [CESR](#ref-CESR) code tables for available algorithms. +decimal, 0x23 in hex). See [CESR](#ref-CESR) code tables for available +algorithms. 3. Compute the digest of the modified serialization, which includes the dummy SAID value. 4. Replace the dummy characters with the computed SAID value. #### How to verify object -1. Convert the object ([bundle](#bundle) or [capture base](#capture-base) or [overlay](#overlays)) -into its canonical form, ensuring all whitespace is removed. +1. Convert the object ([bundle](#bundle) or [capture base](#capture-base) or +[overlay](#overlays)) into its canonical form, ensuring all whitespace is +removed. 2. Replace the SAID field value in the serialization with a dummy string of the same length as the digest algorithm. Use the digest algorithm specified by the [CESR](#ref-CESR) derivation code of the copied SAID. The dummy character is # @@ -923,17 +1112,20 @@ A Code Table for Keys MUST include the following attribute: } ``` -_Example 21. Code snippet for a Code Table for Keys, providing an anchor for, in this case, two-character ISO country codes._ +_Example 21. Code snippet for a Code Table for Keys, providing an anchor for, in +this case, two-character ISO country codes._ #### Code Table for Key-Value pairs -A Code Table for Key-Value pairs provides a mapping of input values to output values. +A Code Table for Key-Value pairs provides a mapping of input values to output +values. A Code Table for Key-Value pairs MUST include the following attribute: - `entries` - The "entries" attribute is a map of key-value pairs, where the key is the input value (the source) and the value is the output value (the product). + The "entries" attribute is a map of key-value pairs, where the key is the + input value (the source) and the value is the output value (the product). ```json { From 7a3d18769a5d5e3a2588719f9a6362245565c9ce Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 13 Feb 2025 15:10:05 +0100 Subject: [PATCH 44/46] chore: reintroduce accidentally removed type --- docs/specification/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/specification/README.md b/docs/specification/README.md index 2128585..89156b5 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -202,6 +202,9 @@ _Listing: ABNF representation of the attribute name_ An attribute type determines the attribute's syntax and how attributes of that type are compared and sorted. A Capture Base recognises seven core data types: +- **Text**: a data type that defines a human-readable sequence of characters and +the words they form, subsequently encoded into computer-readable formats such as +ASCII \[[RFC0020](#ref-RFC0020)\]. - **Numeric**: a data type that defines anything relating to or containing numbers. Examples of numeric data types include 8-byte integers, fixed precision and scale numeric data, floating precision number data, integer (whole number) From ae632b0d87559a8aa49f45d8c806e0ac3eb96c9d Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 13 Feb 2025 15:37:18 +0100 Subject: [PATCH 45/46] chore: remove informative part about classification of overlays --- docs/specification/README.md | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 89156b5..0645873 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -240,15 +240,12 @@ an array instead of many separate variables (e.g., `Array[Text]`, ### Overlays `Overlay` as a task-specific object provides layers of definitional or -contextual metadata. OCA specification recognize two core types of overlays: -- [Semantic overlays](#semantic-overlays) - provide contextual meaning to -describe objects and their relationships. -- [Inputs overlays](#inputs-overlays) - provide predefined inputs for data -attestations. +contextual metadata. -In the context of this specification, these are considered **core overlays**, -which, through **community consensus**, are deemed the most essential for -inclusion and are among the most commonly used. +In the context of this specification, all listed **overlays** are classified as +**core overlays**. These overlays have been identified through community +consensus as fundamental for ensuring semantic interoperability and are among +the most widely utilized. The **OCA Specification** intentionally limits the number of **predefined core overlays** to a **minimum**, allowing the community to take the lead in @@ -327,11 +324,7 @@ The `language` attribute MUST contain either the two-letter language code _Table 1. An example of ISO standard values for language and combined language/country codes._ -### Semantic Overlays -Semantic overlays provide contextual meaning to describe objects and their -relationships. - -##### Character Encoding Overlay +#### Character Encoding Overlay A Character Encoding Overlay defines the process of assigning numbers to graphical characters, especially the written characters of human language, @@ -397,7 +390,7 @@ Encoding Overlay MUST include at least one of the following attributes: _Example 2. Code snippet for a Character Encoding Overlay._ -##### Format Overlay +#### Format Overlay A Format Overlay defines an input and display format for data fields. The data format enables conversion of the input buffer to the program variable and @@ -442,7 +435,7 @@ exchange and communication of date and time-related data. _Example 3. Code snippet for a Format Overlay._ -##### Label Overlay +#### Label Overlay _[language-specific object]_ @@ -480,7 +473,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes) and _Example 5. Code snippet for a Label Overlay (language: en)._ -##### Meta Overlay +#### Meta Overlay _[language-specific object]_ @@ -518,7 +511,7 @@ the scope of this specification. _Example 6. Code snippet for a Meta Overlay (language: en_UK)._ -##### Standard Overlay +#### Standard Overlay A Standard Overlay defines a documented agreement or technical specification published by a standards organisation used to represent, format, define, @@ -553,7 +546,7 @@ standards organisation followed by an internal document identifier. _Example 7. Code snippet for a Standard Overlay._ -### Inputs Overlays +#### Inputs Overlays Inputs overlays provide predefined inputs for data attestations. From f2c42d8e2193e4c33222846c78e0482518856b3e Mon Sep 17 00:00:00 2001 From: Robert Mitwicki Date: Thu, 13 Feb 2025 16:11:34 +0100 Subject: [PATCH 46/46] chore: fix language codes in examples --- docs/specification/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/specification/README.md b/docs/specification/README.md index 0645873..980e912 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -457,7 +457,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes) and "d": "EPstaptvuTLvr6r2b0JBLzxaQzMZKkcKaYZBQTYPrdaL", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/label/1.0.2", - "language": "en_UK", + "language": "en-UK", "attribute_labels": { "dateOfBirth": "Date of birth", "documentNumber": "Passport Number", @@ -502,14 +502,14 @@ the scope of this specification. "d": "EGzJ1hFOPWD1J5Bq2TA-NR0ssPunJJO_7uxngJNDXcXs", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/meta/1.0.2", - "language": "en_UK", + "language": "en-UK", "name": "Digital Passport", "description": "An example of a Digital Passport schema", "affiliation": "The Government of Antarctica" } ``` -_Example 6. Code snippet for a Meta Overlay (language: en_UK)._ +_Example 6. Code snippet for a Meta Overlay (language: en-UK)._ #### Standard Overlay @@ -700,7 +700,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), and "d": "EKnniFpc80_9VqcJjHnywYtHZEaq12d5i1Bo6Va6VAiZ", "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis", "type": "spec/overlays/entry/1.0.2", - "language": "en_UK", + "language": "en-UK", "attribute_entries": { "documentType": { "PE": "DIPLOMATIC PASSPORT", @@ -716,7 +716,7 @@ In addition to the [Mandatory attributes](#mandatory-attributes), and } ``` -_Example 12. Code snippet for an Entry Overlay (language: en_UK)._ +_Example 12. Code snippet for an Entry Overlay (language: en-UK)._ #### Unit Overlay @@ -989,7 +989,7 @@ with the specification. "d": "ECZc26INzjxVbNo7-hln6xN3HW3e1r6NGDmA5ogRo6ef", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", "type": "spec/overlays/label/1.0", - "language": "en_UK", + "language": "en-UK", "attribute_labels": { "d": "Schema digest", "i": "Credential Issuee", @@ -1010,7 +1010,7 @@ with the specification. "d": "EIBXpVvka3_4lheeajtitiafIP78Ig8LDMVX9dXpCC2l", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", "type": "spec/overlays/information/1.0", - "language": "en_UK", + "language": "en-UK", "attribute_information": { "d": "Schema digest", "i": "Credential Issuee", @@ -1031,7 +1031,7 @@ with the specification. "d": "EOxvie-zslkGmFzVqYAzTVtO7RyFXAG8aCqE0OougnGV", "capture_base": "EBnF9U9XW1EqteIW0ucAR4CsTUqojvfIWkeifsLRuOUW", "type": "spec/overlays/meta/1.0", - "language": "en_UK", + "language": "en-UK", "description": "Entrance credential", "name": "Entrance credential" }