SC1 – Common Data Types

Version: 0.9.0
Status: Release Candidate
Type: Normative Common Specification

Copyright © 2026 inside workspace GmbH
This work is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.

1. Introduction

1.1 Purpose

This specification defines the reusable data types used throughout the KAPRI Specification Suite.

The defined data types provide a common semantic foundation for all schema specifications and ensure consistent interpretation, serialization and validation across independent implementations.

This specification defines the meaning of each data type independently of any specific Package component.

Package-specific object models, properties and business semantics are defined by the corresponding schema specifications.

1.2 Scope

This specification defines:

reusable common data types,
their semantic meaning,
serialization requirements,
validation requirements.

This specification does not define:

Package-specific object models,
Package-specific properties,
organizational roles,
business semantics.

The use of the defined data types is specified by the corresponding schema specifications.

1.3 Relationship to Other Specifications

This specification is part of the KAPRI Specification Suite.

The common data types defined by this specification are referenced by:

S1 – Package Manifest Schema
S2 – Packing List Schema
S3 – Composition Schema
S4 – KAP Key Delivery Message Schema

Schema specifications SHALL reuse the data types defined by this specification whenever applicable and SHALL NOT redefine their semantics.

The key words “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, and “MAY” in this specification are to be interpreted as described in RFC 2119.

2. Design Principles

The common data types defined by this specification SHALL adhere to the following architectural principles.

2.1 Single Responsibility

Each data type SHALL represent exactly one reusable concept.

A data type SHALL NOT combine multiple independent concepts.

2.2 Stable Semantics

The semantic meaning of a data type SHALL remain stable across all schema specifications.

The interpretation of a data type SHALL NOT depend on the Package component in which it is used.

2.3 Reusability

Common data types SHALL be independent of individual Package components.

The same data type MAY be referenced by multiple schema specifications.

2.4 Separation of Data Types and Business Semantics

This specification defines reusable data types only.

Package-specific concepts, organizational roles and business semantics SHALL be defined by the corresponding schema specifications.

2.5 Backward Compatibility

Future versions of this specification MAY introduce additional data types.

Existing data types SHALL remain backward compatible whenever reasonably possible.

3. Common Data Type Categories

The common data types defined by this specification are organized into logical categories according to their architectural purpose.

3.1 Identification Types

Data types used to uniquely identify architectural entities and their versions.

Examples include:

Identifier
Version Identifier
Schema Version

3.2 Organization Types

Data types representing organizations participating in the publication or processing of Knowledge Asset Packages.

Examples include:

Organization

3.3 Reference Types

Data types used to reference physical or logical resources.

Examples include:

URI
File Path
Language Tag
Media Type
Document Reference

3.4 Security Types

Data types supporting integrity, authenticity and cryptographic verification.

Examples include:

Hash
Hash Algorithm
Signature
Certificate Reference
Key Identifier
Encrypted File Key

3.5 Temporal Types

Data types representing points in time and validity intervals.

Examples include:

Timestamp
Validity Period

3.6 File Types

Data types describing files contained within a Knowledge Asset Package.

Examples include:

File Identifier
File Size

4. Type Definitions

This chapter defines the reusable common data types referenced by the schema specifications of the KAPRI Specification Suite.

Each data type represents a single architectural concept with stable semantics that are independent of any specific Package component.

The serialization and validation requirements defined for each data type apply wherever that type is referenced by a schema specification.

4.1 Identifier

Definition

An Identifier uniquely identifies an architectural entity within its defined scope.

Semantics

An Identifier provides a stable reference to an entity throughout its lifetime.

The scope and uniqueness requirements of an Identifier are defined by the referencing schema specification.

Serialization

An Identifier SHALL be serialized as a JSON string.

Validation

The Identifier SHALL conform to the syntax defined by the referencing schema specification.

4.2 Version Identifier

Definition

A Version Identifier uniquely identifies a specific version of an architectural entity.

Semantics

Version Identifiers distinguish different published states of the same entity.

The versioning strategy is defined by the corresponding schema specification or reference model.

Serialization

A Version Identifier SHALL be serialized as a JSON string.

Validation

The Version Identifier SHALL conform to the syntax defined by the referencing specification.

4.3 Schema Version

Definition

A Schema Version identifies the version of a schema specification used for serialization and validation.

Semantics

Schema Versions enable receiving implementations to select the appropriate schema definition.

Serialization

A Schema Version SHALL be serialized as a JSON string.

Validation

The Schema Version SHALL identify a published version of the referenced schema.

4.4 Organization

Definition

An Organization represents a legal or organizational entity participating in the creation, publication or processing of a Knowledge Asset Package.

Semantics

This data type represents organizational identity only.

Package-specific organizational roles, such as Responsible Organization, are defined by the corresponding schema specifications.

Serialization

An Organization SHALL be serialized as a JSON object.

The internal structure of the object is defined by the referencing schema specification.

Validation

An Organization SHALL contain all mandatory properties required by the referencing schema specification.

4.5 URI

Definition

A Uniform Resource Identifier (URI) identifies a resource using a globally unique identifier.

Semantics

A URI provides a standardized reference to a resource outside the semantic structure of the Package.

URIs SHALL conform to RFC 3986.

Serialization

A URI SHALL be serialized as a JSON string.

Validation

The URI SHALL conform to RFC 3986.

4.6 File Path

Definition

A File Path identifies the location of a file within a Knowledge Asset Package.

Semantics

A File Path is a relative path within the Package.

It identifies the physical location of a serialized file and SHALL NOT be interpreted as a URI.

Serialization

A File Path SHALL be serialized as a JSON string using “/” as the path separator.

Validation

A File Path:

SHALL be relative,
SHALL NOT contain path traversal segments (for example “../”),
SHALL identify a file contained within the Package.

4.7 Language Tag

Definition

A Language Tag identifies the natural language associated with textual content.

Semantics

Language Tags enable multilingual interoperability.

Language Tags SHALL conform to BCP 47.

Serialization

A Language Tag SHALL be serialized as a JSON string.

Validation

The Language Tag SHALL conform to BCP 47.

4.8 Media Type

Definition

A Media Type identifies the representation format of a file or resource.

Semantics

Media Types describe the format of serialized resources independently of their semantic meaning.

Media Types SHALL conform to RFC 6838.

Serialization

A Media Type SHALL be serialized as a JSON string.

Validation

The Media Type SHALL conform to RFC 6838.

4.9 Document Reference

Definition

A Document Reference identifies a Package document and provides the information required to verify its integrity.

Semantics

A Document Reference establishes a stable reference to another document contained in the same Knowledge Asset Package.

It uniquely identifies the referenced document and provides the cryptographic hash required for integrity verification.

Structure

A Document Reference SHALL contain the following properties.

Serialization

A Document Reference SHALL be serialized as a JSON object.

Validation

The referenced document_id SHALL uniquely identify a Package document.
The hash SHALL correspond to the referenced document.
The hash_algorithm SHALL identify the algorithm used to calculate the hash.

4.10 Hash

Definition

A Hash represents the cryptographic digest of serialized data.

Semantics

Hashes enable integrity verification by detecting unintended or unauthorized modifications.

The hash value is independent of the algorithm used to calculate it.

Serialization

A Hash SHALL be serialized as a JSON string.

Validation

The Hash SHALL conform to the syntax required by the selected hash algorithm.

4.11 Hash Algorithm

Definition

A Hash Algorithm identifies the cryptographic algorithm used to calculate a Hash.

Semantics

The selected algorithm determines how the corresponding Hash value was generated.

Serialization

A Hash Algorithm SHALL be serialized as a JSON string.

Validation

The algorithm SHALL identify a supported cryptographic hash algorithm.

Every conforming implementation SHALL support at least SHA-256.

Implementations MAY support additional hash algorithms.

4.12 Signature

Definition

A Signature represents the digital signature providing cryptographic evidence for the integrity and authenticity of a serialized Package component.

Semantics

A Signature provides cryptographic evidence that:

the protected document has not been modified since it was signed,
the signature was created using the private key corresponding to the signing certificate,
the corresponding signing certificate can be identified through the associated certificate chain.

A Signature protects the integrity and authenticity of the serialized document.

A Signature does not by itself establish trust in the organization represented by the associated certificate chain. Validation of the certificate chain and trust decisions are performed by the receiving implementation according to its applicable trust policy.

Structure

PropertyCardinalityDescriptionalgorithm | 1 | Cryptographic signature algorithm used to create the signature.
certificate_chain | 1 | Certificate chain required to validate the digital signature, expressed as an ordered array (1..n entries) of Certificate Reference (see SS4.13), leaf certificate first.
signature_value | 1 | Digital signature over the canonical representation of the protected document.

Serialization

When referenced by a schema specification, a Signature SHALL be serialized as the value of a property named signature.

The signature property SHALL NOT be included in the canonical representation used to calculate the digital signature.

Validation

A Signature SHALL contain all mandatory properties defined by this specification.

The receiving implementation SHALL verify:

the syntactic correctness of the Signature object,
the integrity of the protected document,
the validity of the digital signature using the associated certificate chain.

Validation of certificate trust, authorization policies, and acceptance of the signer are outside the scope of this specification and are determined by the receiving implementation.

The algorithm SHALL identify a cryptographic signature algorithm supported by the receiving implementation.

This specification intentionally does not mandate a specific signature algorithm. The set of algorithms considered supported for a given exchange is defined by the applicable Cryptographic Profile (see R0 – Reference Implementation Specification / T1 – Public Key Infrastructure for the profile used by the KAPRI Reference Implementation).

4.13 Certificate Reference

Definition

A Certificate Reference identifies one certificate within a certificate chain and embeds the information required to independently validate it, without requiring the receiving implementation to resolve the certificate from an external source.

Semantics

A Certificate Reference is self-contained: it carries the complete certificate alongside a short identifier and human-readable issuer/serial information, so that a Signature’s certificate_chain can be validated using only the information present in the signed document itself.

Resolution of a Certificate Reference against an external trust store or PKI is unnecessary for structural and cryptographic chain validation. It MAY still be used by a receiving implementation for trust decisions (see S0 - Package Validation), which remain outside the scope of this specification.

Structure

A Certificate Reference SHALL contain the following properties.

Property Semantics

certificate_id

A short, stable identifier for the referenced certificate (e.g. a thumbprint-based URI). Enables cheap comparison and caching without parsing the certificate.

issuer

The Distinguished Name of the certification authority that issued the referenced certificate, in RFC 2253 string form. Provided for human-readable inspection and logging; not itself used for cryptographic validation.

serial_number

The serial number of the referenced certificate, as assigned by the issuing certification authority, serialized as a decimal string.

certificate

The complete certificate in DER encoding, Base64-encoded per RFC 4648 SS4 (standard alphabet, with padding) - the same encoding conventionally used for embedding X.509 certificates (e.g. the body of a PEM block, or ds:X509Certificate in XMLDSig).

Serialization

A Certificate Reference SHALL be serialized as a JSON object containing the properties defined above.

Validation

The certificate property SHALL decode to a syntactically valid DER-encoded X.509 certificate.

Where a Signature’s certificate_chain contains more than one Certificate Reference, the chain SHALL be ordered leaf certificate first, and each certificate other than the last SHALL be issued by the certificate immediately following it (the following certificate’s subject SHALL equal the given certificate’s issuer, and the given certificate’s signature SHALL validate against the following certificate’s public key). The last certificate in the chain SHALL be self-issued (subject equals issuer, signature validates against its own public key).

4.14 Encrypted File Key

Definition

An Encrypted File Key represents a file encryption key encrypted for one intended recipient.

Semantics

An Encrypted File Key contains the encrypted symmetric key required to decrypt one encrypted Package File.

Each Encrypted File Key SHALL be associated with exactly one Key Identifier.

The encryption algorithm and key management procedures are defined by the referencing schema specification.

The encrypted key is recipient-specific and SHALL NOT be interpreted outside the context of the corresponding Key Delivery Message.

Serialization

An Encrypted File Key SHALL be serialized as a JSON string.

The encoding of the encrypted value is defined by the referencing schema specification.

Validation

An Encrypted File Key SHALL conform to the encoding and syntax required by the referencing schema specification.

Cryptographic validation and successful decryption are outside the scope of this specification.

4.15 Key Identifier

Definition

A Key Identifier uniquely identifies a symmetric File Encryption Key.

Semantics

A Key Identifier provides a stable reference to a symmetric File Key independently of how that File Key is distributed or encrypted.

The corresponding encrypted File Key MAY be delivered by one or more Key Delivery Messages.

Serialization

A Key Identifier SHALL be serialized as a URI.

Validation

A Key Identifier SHALL conform to RFC 3986.

4.16 Timestamp

Definition

A Timestamp represents a single point in time.

Semantics

Timestamps describe publication, creation or validation events.

Unless otherwise specified, timestamps SHALL be expressed in Coordinated Universal Time (UTC).

Serialization

A Timestamp SHALL be serialized according to ISO 8601.

Validation

The Timestamp SHALL conform to ISO 8601.

4.17 Validity Period

Definition

A Validity Period defines the interval during which an entity is considered valid.

Semantics

A Validity Period consists of a mandatory start timestamp and an optional end timestamp.

Serialization

A Validity Period SHALL be serialized as an object containing the defined timestamps.

Validation

If an end timestamp is present, it SHALL NOT precede the start timestamp.

4.18 File Identifier

Definition

A File Identifier uniquely identifies a file within a Knowledge Asset Package.

Semantics

A File Identifier provides a stable reference to a file independent of its physical location or file name.
A File Identifier remains stable even if the corresponding File Path changes.

Serialization

A File Identifier SHALL be serialized as a JSON string.

Validation

The File Identifier SHALL conform to the syntax defined by the referencing schema specification.

4.19 File Size

Definition

A File Size represents the size of a serialized file in bytes.

Semantics

File Size supports completeness and integrity verification.

Serialization

A File Size SHALL be serialized as a non-negative integer.

Validation

A File Size SHALL be greater than or equal to zero.

5. Serialization Requirements

This chapter defines the serialization requirements applicable to the common data types defined by this specification.

The general serialization rules are specified by SC0 – Common Serialization Rules.

Schema specifications referencing the data types defined by this specification SHALL serialize them in accordance with both SC0 and the requirements defined in this chapter.

5.1 General Requirements

Common data types SHALL be serialized using the rules defined by SC0.

Each data type SHALL have exactly one canonical serialized representation.

Serialization SHALL preserve the semantic meaning of the referenced data type.

5.2 Identifier Types

Identifier Types SHALL be serialized as JSON strings.

The serialized representation SHALL preserve the identifier value exactly as defined by the referencing schema specification.

Serialization SHALL NOT modify, normalize or truncate identifier values.

5.3 Organization Types

Organization Types SHALL be serialized as JSON objects.

The internal structure of an Organization is defined by the referencing schema specification.

The serialized representation SHALL be independent of any package-specific organizational role.

5.4 Reference Types

Reference Types SHALL use their standardized serialized representation.

Where applicable:

URIs SHALL conform to RFC 3986.
Language Tags SHALL conform to BCP 47.
Media Types SHALL conform to RFC 6838.

File Paths SHALL:

be serialized as relative JSON strings,
use “/” as the path separator,
identify locations within the Package.

5.5 Security Types

Security Types SHALL be serialized using the representation defined by the referencing schema specification.

Binary values SHALL use the encoding specified by the referencing schema.

The canonical representation used for digital signatures SHALL be defined by the referencing schema specification.

Encrypted File Keys SHALL be serialized using the encoding defined by the referencing schema specification.

5.6 Temporal Types

Timestamp values SHALL be serialized according to ISO 8601.

Unless otherwise specified, timestamps SHALL represent Coordinated Universal Time (UTC).

Validity Periods SHALL consist of a mandatory start timestamp and an optional end timestamp.

5.7 File Types

File Identifiers SHALL be serialized as JSON strings.

File Sizes SHALL be serialized as non-negative integer values representing the number of bytes.

6. Validation Requirements

This chapter defines the validation requirements applicable to the common data types defined by this specification.

Validation performed according to this specification is limited to the syntactic correctness of the serialized data types.

Validation of package consistency, semantic correctness, cryptographic trust, authorization policies and interoperability is outside the scope of this specification and is defined by the corresponding schema specifications or by S0 – Knowledge Asset Package Architecture Specification.

6.1 General Requirements

Every serialized data type SHALL conform to the validation requirements defined by this specification.

Validation of a data type SHALL be independent of the Package component in which it is used.

Failure to validate a referenced data type SHALL cause validation of the containing object to fail.

6.2 Identifier Types

Identifier Types SHALL conform to the syntax defined by the referencing schema specification.

Where uniqueness is required, the corresponding schema specification SHALL define the applicable scope.

6.3 Organization Types

Organization Types SHALL contain all mandatory information required by the referencing schema specification.

Validation of organizational roles and responsibilities is outside the scope of this specification.

6.4 Reference Types

Reference Types SHALL conform to the applicable standards.

Where applicable:

URIs SHALL conform to RFC 3986.
Language Tags SHALL conform to BCP 47.
Media Types SHALL conform to RFC 6838.

File Paths:

SHALL be relative,
SHALL NOT contain path traversal segments such as ..,
SHALL identify files located within the Package.

6.5 Security Types

Hash values SHALL conform to the syntax required by the selected hash algorithm.

Encrypted File Keys SHALL conform to the syntax and encoding required by the referencing schema specification.

Signature objects SHALL conform to the structure defined by this specification.

Cryptographic verification of digital signatures, certificate chains and trust relationships is outside the scope of this specification.

6.6 Temporal Types

Timestamp values SHALL conform to ISO 8601.

Validity Periods SHALL contain a mandatory start timestamp.

If an end timestamp is present, it SHALL NOT precede the start timestamp.

6.7 File Types

File Identifiers SHALL conform to the syntax defined by the referencing schema specification.

File Sizes SHALL be non-negative integer values representing the size of the serialized file in bytes.

7. Conformance

This chapter defines the conformance requirements for implementations using the common data types specified by this specification.

Conformance to this specification ensures that common data types are interpreted, serialized and validated consistently across all schema specifications of the KAPRI Specification Suite.

7.1 General Conformance

An implementation claiming conformance with this specification SHALL implement every common data type referenced by the schema specifications it supports.

Referenced data types SHALL be interpreted, serialized and validated in accordance with:

SC0 – Common Serialization Rules, and
this specification.

7.2 Referenced Data Types

Schema specifications SHALL reuse the common data types defined by this specification whenever applicable.

Schema specifications SHALL NOT alter the semantics of a referenced common data type.

Additional constraints MAY be defined by the referencing schema specification, provided they do not contradict this specification.

7.3 Consistent Interpretation

Conforming implementations SHALL interpret common data types consistently across all Package components.

The semantic meaning of a common data type SHALL be independent of the schema specification in which it is referenced.

7.4 Extensibility

Future versions of this specification MAY introduce additional common data types.

Existing data types SHOULD remain backward compatible whenever reasonably possible.

Implementations SHOULD ignore unknown data types unless their interpretation is required by a referenced schema specification or implementation profile.

7.5 Relationship to Schema Specifications

This specification defines reusable common data types only.

Package-specific object models, properties, validation rules and business semantics are defined by the corresponding schema specifications.

Conformance with this specification does not imply conformance with any individual schema specification.

Conformance with a schema specification requires conformance with:

SC0 – Common Serialization Rules,
SC1 – Common Data Types, and
the referenced schema specification.

Schema specifications SHALL reuse the common data types defined by this specification rather than redefining equivalent data types.

SC1 – Common Data Types

1. Introduction

2. Design Principles

Kontakt

Login