OUDEA v0.1

1. Overview

OUDEA provides a common architectural frame for governed, machine-readable data entities that can be published, discovered, referenced, and exchanged across independent systems.

2. Introduction

2.1 What OUDEA is

OUDEA is an open architecture and canonical specification for interoperable structured-data exchange.

What OUDEA standardizes. OUDEA standardizes implementation-independent public contracts for DEID identity, classification, references, discovery and public index projection, Find resolution, and Exchange. Internal storage, processing pipelines, component topology, and orchestration are implementation-defined and are not part of the OUDEA Core specification.

2.2 Why OUDEA

Data exchanged across independent systems is often coupled to changing infrastructure, local identifiers, application-specific metadata, or centralized catalogs. OUDEA separates the stable identity of a governed data entity from the infrastructure currently used to publish and exchange it.

OUDEA allows independently governed domains to retain authority over their own DEID namespaces, Classes, Schemas, and published supply while exposing a common machine-readable model for cross-system discovery and exchange. This makes data entities portable across infrastructure changes without requiring one central platform or one implementation.

OUDEA also separates discovery, relationship navigation, resolution, and data access. Search discovers relevant DEIDs; References connect governed data entities; Find resolves a known DEID to its current access infrastructure; and Exchange transfers the actual data. Where the consumer does not already know the DEID, the normal operational sequence is Search → Find → Exchange.

2.3 What OUDEA is not

OUDEA is not a single software product, centralized data platform, prescribed deployment topology, or requirement to use one implementation.

OUDEA is not a universal data-product ontology, catalog vocabulary, provenance model, rights-expression language, or domain ontology.

3. Scope

OUDEA v0.1 focuses on the architectural concepts and public interoperability contracts required to identify, classify, publish, discover, reference, resolve, and exchange governed data entities.

4. Relationship to Existing Standards

OUDEA does not define a universal semantic model for data products, catalogs, provenance, rights, or domain vocabularies. External standards and vocabularies may describe OUDEA-governed data entities without replacing OUDEA identity, references, discovery, resolution, federation, or exchange semantics.

A DEID representing a data product MAY additionally be described using a data-product model such as DPROD. OUDEA remains responsible for its governed identity and operational participation in the federated exchange architecture.

5. Terminology

OUDEA uses a controlled vocabulary. The separate OUDEA Terminology document is normative for defined terms used by this specification.

6. Core Principles

6.1 DEID rules

A DEID is a globally unique, canonical HTTPS identifier controlled by its governance domain. It identifies the governed data entity independently of infrastructure and versioning, remains stable across infrastructure changes, and MUST NOT be reassigned to another entity.

6.2 Class and Schema validation

Every DEID MUST declare a governance domain and a canonical OUDEA class URI. A DEID MAY declare a schema. A DEID without a Schema remains conforming.

The canonical class is governed by the DEID's domain. An OPTIONAL external_class MAY align the OUDEA Class with an external vocabulary, but it does not replace the canonical OUDEA Class. external_class is informational semantic metadata and does not by itself determine OUDEA identity, governance, validation, classification, discovery, resolution, or Exchange behavior.

DOMAIN
cities.app
    |
    +-- CLASS
    |   https://cities.app/class/City
    |      |
    |      +-- external_class
    |      |   https://schema.org/City
    |      |
    |      +-- DEID
    |          https://cities.app/de/be/berlin
    |
    +-- CLASS
        https://cities.app/class/water/DrinkingWaterQuality
           |
           +-- SCHEMA
           |   https://cities.app/schema/water/drinking-water-quality
           |
           +-- DEID
               https://cities.app/de/be/berlin/water/drinking-water-quality

A Class MAY have multiple Schemas. Different supply-types associated with the same DEID MAY use different Schemas, provided all declared Schemas semantically roll up to the DEID's declared Class. Each individual supply-type MAY declare zero or one Schema.

Each Schema document MUST carry an explicit schema/document version. If a Schema is provided, OUDEA MUST validate at publish time that the declared Schema is valid for the declared Class relationship. Validation of a supply payload against its declared Schema is a separate validation concern from validation of the DEID metadata itself.

Linked DEID examples

These examples are loaded directly from the files in examples/. Updating an example JSON file updates the representation shown on this page.

{
   "@context": "https://bytem.app/deid",
   "version": "v0.001",
   "domain": "cities.app",
   "class": "https://cities.app/class/City",
   "external_class": "https://schema.org/City",
   "deid": "https://cities.app/de/be/berlin",
   "label": "Berlin",
   "ags": "11000000",
   "country": "DE",
   "region": "BE",
   "location": {
     "lat": 52.51767,
     "lon": 13.405538,
     "location_mode": "fixed"
   },
   "demand_room_policy": "reuse"
}

{
   "@context": "https://bytem.app/deid",
   "version": "v0.001",
   "domain": "cities.app",
   "class": "https://cities.app/class/water/DrinkingWaterQuality",
   "schema": "https://cities.app/schema/water/drinking-water-quality",
   "deid": "https://cities.app/de/be/berlin/water/drinking-water-quality",
   "label": "Berlin — Trinkwasserqualität",
   "ags": "11000000",
   "country": "DE",
   "region": "BE",
   "location": {
     "lat": 52.51767,
     "lon": 13.405538,
     "location_mode": "fixed"
   },
   "demand_room_policy": "reuse"
}

{
   "@context": "https://bytem.app/deid",
   "version": "v0.001",
   "domain": "legalentities.app",
   "class": "https://legalentities.app/class/LegalEntityPortfolio",
   "schema": "https://legalentities.app/schema/legal-entity-portfolio",
   "deid": "https://legalentities.app/portfolio/example-portfolio",
   "label": "Example Legal Entity Portfolio",
   "location": {
     "location_mode": "none"
   },
   "demand_room_policy": "reuse",
   "demand_references": [
     {
       "deid": "https://legalentities.app/de/lei/7LTWFZYICNSX8D621K86",
       "role": "part_of",
       "label": "Deutsche Bank"
     },
     {
       "deid": "https://legalentities.app/de/lei/851WYGNLUQLFZBSYGB56",
       "role": "part_of",
       "label": "Commerzbank"
     }
   ],
   "product": {
     "description": "A curated portfolio of legal entities, exchangeable as a complete aggregate or by resolving referenced DEIDs individually."
   }
}

6.3 Data Authority

Data Authority. A governance domain is authoritative for the identity and semantic definition of a DEID. The authoritative supply is responsible for the published supply-types, their payloads, schemas and versions associated with that DEID. Public indexes, Find documents, demand-side copies and other derived projections are not authoritative sources of the underlying data. Exchange MUST retrieve data from the authoritative supply identified through the current resolution process.

DOMAIN AUTHORITY
DEID · Class · Schema · References
         |
         v
       DEID
         |
         v
SUPPLY AUTHORITY
Supply-types · Payloads · Versions
         |
         +--------> PUBLIC INDEX
         |          derived metadata
         |
         +--------> FIND
         |          current resolution
         |
         +--------> EXCHANGE
                    transferred data
                          |
                          v
                       DEMAND
                    derived copy

Supply item identity

A DEID identifies the governed entity. supply_type identifies the delivery form of a supplied item, for example a dataset, API, HTML representation or reference. asset_key identifies a distinct supplied item within that DEID, and asset_version identifies a revision of that supplied item.

Within a DEID, the combination supply_type + asset_key identifies the supplied asset. Two distinct assets under the same DEID MUST NOT share the same supply_type + asset_key identity. An asset_key is scoped to its DEID and MAY be reused under different DEIDs. Multiple revisions of the same logical supplied item SHOULD retain the same asset_key and differ by asset_version. supply_type alone is not sufficient to identify a supplied item.

DEID                  which governed entity?
  |
  +-- supply_type     what delivery form?
  |
  +-- asset_key       which supplied item?
  |
  +-- asset_version   which revision?

6.4 Exchange Authority

Exchange Authority. The public index exposes only the standardized minimal metadata required for discovery of a DEID and MUST NOT be treated as a source of the underlying data. Exchange is the OUDEA operation that requests and transfers all currently exchangeable authoritative supply items for a resolved DEID under the current Find result and any applicable terms.

In OUDEA v0.1, Exchange is DEID-wide by default: where a DEID contains multiple supply-types or multiple supply items, all currently exchangeable supply items are included. For each included supply item, the latest authoritative version is exchanged by default. Historical or version-targeted exchange is outside the v0.1 Core and may be considered in later OUDEA versions based on implementation and community requirements.

A public URL or API referenced by OUDEA supply remains independently accessible according to the governance, availability, and terms of its original publisher. The existence of that public URL or API does not itself constitute an OUDEA Exchange. Where such a public resource is represented as OUDEA supply, it MAY also be included in the OUDEA Exchange while remaining independently accessible.

A successful Exchange creates a transferred demand-side copy. It does not transfer authority over the original DEID or its underlying source data to the demand side.

Exchange MUST fail where the DEID cannot currently be resolved, where no authoritative exchangeable supply is available, or where applicable exchange conditions are not satisfied. Exact protocol or HTTP error mappings may be defined separately.

PUBLIC INDEX
minimal discovery metadata
         |
         v
       DEID
         |
         v
       FIND
current resolution
         |
         v
  AUTHORITATIVE SUPPLY
         |
         +-- supply-type-json
         |      latest version
         |
         +-- supply-type-dataset
         |      latest version
         |
         +-- supply-type-api
         |      latest version
         |
         +-- other exchangeable supply
         |
         v
     EXCHANGE
all exchangeable supply-items
for the DEID by default
         |
         v
       DEMAND
transferred copy


PUBLIC URL / API
         |
         +--> remains independently accessible
              under publisher governance

         +--> MAY also be represented as OUDEA supply
              and included in Exchange

6.5 Data entity and product thinking

Normative rule. A data product MAY be represented by a DEID. Not every DEID is a data product. External models MAY describe a DEID that represents a data product.

A DEID representing a data product MAY use a Schema whose semantic model is based on or aligned with an external data-product, metadata, provenance, rights, general semantic, or domain-specific model such as DPROD, DCAT, schema.org, PROV, ODRL, or another compatible model. Such models complement but do not replace OUDEA identity, classification, References, resolution, or Exchange semantics.

Operational role and resource kind

OUDEA defines implementation-independent operational roles and resource kinds. A protocol binding MAY map these concepts to protocol-specific containers such as Matrix rooms.

OUDEA v0.1 defines the Core operational roles supply, demand, and exchange, and the Core resource kinds entity, dataset, and product. Additional resource kinds may be introduced by later OUDEA versions. Resource kind does not replace the canonical Class.

OUDEA DEID
    |
    +-- operational_role
    |      supply | demand | exchange
    |
    +-- resource_kind
    |      entity | dataset | product
    |
    +-- class
           canonical domain semantics
           |
           +-- schema
                  optional semantic / structural refinement

6.6 DEID References

A DEID Reference is a directional, qualified relationship from one governed DEID to another. In the v0.1 public DEID document, demand-side references are represented by the OPTIONAL demand_references field. This field is distinct from supply-side reference mechanisms. References are not inferred from URL structure, shared Class, shared Domain, or implementation topology.

SOURCE DEID
https://legalentities.app/portfolio/example-portfolio
         |
         +-- part_of ----> Deutsche Bank DEID
         |
         +-- part_of ----> Commerzbank DEID

REFERENCE RULES
- references are directional; no reciprocal reference is required
- successful Exchange does not depend on a backlink from the target
- duplicate (deid, role) pairs are forbidden
- array order has no semantic meaning
- a Reference does not transfer authority over the target
- direct References are evaluated one DEID at a time
- nested References are not recursively auto-exchanged

A temporarily unavailable referenced DEID does not by itself invalidate the identity of the source DEID. Resolution may fail because of network, infrastructure, or availability conditions, and OUDEA does not guarantee the availability of underlying infrastructure.

If a product is exchanged as a complete aggregate, all directly referenced part_of DEIDs MUST resolve before that aggregate Exchange can complete. OUDEA v0.1 does not define implicit partial aggregate success.

A consumer MAY inspect References whenever composition or navigation is relevant. Each referenced DEID may then be handled independently through Find and Exchange. Find can resolve that DEID's current extended metadata and infrastructure/access information; nested DEIDs are evaluated one at a time.

6.7 Linked DEID examples

The linked example set consists of a Berlin City entity, a Berlin DrinkingWaterQuality dataset, and a LegalEntityPortfolio product with part_of References. The complete JSON files in examples/ are the source of truth for the examples rendered by this page.

The examples expose OUDEA public contracts only. They do not expose raw Matrix state events, room internals, queue/event flows, exact bot architecture, or other implementation-specific structures.

6.8 Open implementation and trademark boundary

Open implementation. OUDEA defines public interoperability contracts rather than one mandatory software implementation. Any implementation may use different internal storage, processing, topology, orchestration, user interface, or deployment design while targeting the same published OUDEA contracts and applicable protocol binding.

OUDEA conformance MUST NOT require use of bytEM or Liberbyte-hosted infrastructure. The specification documentation license governs the specification text; software implementations may use separate licenses.

Trademark boundary. OUDEA™ is claimed as a trademark of Liberbyte GmbH. Third parties may refer descriptively to the OUDEA specification or version they target, but such use must not imply sponsorship, certification, endorsement, or canonical status. Trademark policy is separate from the right to independently implement the public architecture.

6.9 Matrix substrate

OUDEA v0.1 uses Matrix federation as its initial protocol substrate. OUDEA Core remains expressed in implementation-independent concepts; the protocol binding maps those concepts to Matrix where interoperability requires it.

In particular, OUDEA Core defines operational roles such as supply, demand, and exchange, and resource kinds such as entity, dataset, and product. The Matrix binding may map them to Matrix-specific containers.

Raw Matrix event/state layouts, internal room structure, bot architecture, queues, security/access-control implementation, deployment topology, and other bytEM internals are not OUDEA Core merely because the reference implementation uses them.

6.10 Structured interoperability

OUDEA public contracts are intended to be machine-readable so that independent implementations can validate and exchange the same structures without relying on private implementation knowledge.

The repository reserves schemas/ for future machine-readable OUDEA public contracts. OUDEA v0.1 defines its normative interoperability requirements in the specification itself; no machine-readable schema is required for v0.1 conformance.

6.11 FAIR alignment

FAIR provides guiding principles for making digital objects Findable, Accessible, Interoperable, and Reusable; it is not itself an implementation standard. OUDEA can support FAIR-oriented systems, but use of OUDEA does not by itself make a data object or implementation FAIR-compliant.

Primary FAIR sources: GO FAIR — FAIR Principles and Wilkinson et al., The FAIR Guiding Principles for scientific data management and stewardship (2016). See also the repository FAIR mapping.

6.12 Federation and resolution

OUDEA separates persistent identity from current infrastructure. A DEID remains the stable identifier of its governed entity while Find resolves that DEID to the current information required for access through the applicable protocol binding.

Federation MUST NOT require a DEID to encode a server, room identifier, deployment, storage location, or other replaceable infrastructure detail. A failure to reach current infrastructure MUST be treated as an operational resolution failure rather than as permission to silently replace the DEID.

6.13 Security and trust

Security and Trust. OUDEA standardizes who is authoritative for identity and data, and how governed data is discovered, resolved and exchanged; it does not prescribe one universal security implementation.

Trust is scoped, not global. A participant may rely on a Domain Authority for DEID identity and semantics, a Supply Authority for the data it publishes, and infrastructure or protocol components for the transport/security functions they perform. Trust in one layer does not imply trust in every other layer.

Internal Matrix power levels, room membership policy, credential storage, secrets management, key rotation, bot permissions, firewalling, deployment isolation and similar implementation controls are outside OUDEA Core unless later standardized as public interoperability requirements.

6.14 Lifecycle and readiness

Lifecycle and Readiness. OUDEA v0.1 does not require a fixed lifecycle sequence for governed data entities. Implementations MAY expose lifecycle or market-status labels such as draft, reserved, advertised or exchangeable, but interoperability MUST be determined from observable capabilities rather than from a specific label sequence.

A registered DEID MAY be discoverable before it is exchangeable. A DEID MAY become exchangeable without passing through a separate advertised state. Exchange readiness SHOULD be determined from the applicable registration, supply and access conditions rather than solely from a lifecycle or market-status label.

Temporary network, infrastructure or resolution failures do not automatically change lifecycle or readiness semantics and do not invalidate DEID identity; OUDEA does not guarantee underlying infrastructure availability.

Future states. Later OUDEA versions MAY introduce additional lifecycle, access, quality or commercial states, for example restricted/authenticated Exchange, license-controlled access, preview supply, certification assertions, deprecation, pay-per-use, subscriptions or paid licensed Exchange. A future version MAY also define an explicit withdrawn or tombstone state for a DEID that was previously registered and is deliberately retired by its governing domain. Such a state could distinguish an unknown identifier from a deliberately withdrawn one. These are not normative v0.1 states.

6.15 Version compatibility

Later OUDEA versions SHOULD preserve backward compatibility with earlier versions where reasonably possible. If a later version introduces a breaking change to an existing normative contract, that incompatibility MUST be explicit and documented. Implementations MUST NOT silently treat incompatible versions as equivalent.

OUDEA v0.1 does not define an automatic specification-version negotiation mechanism. Asset versioning is separate: the DEID remains stable and v0.1 Exchange returns the latest authoritative version of each exchangeable supply item by default.

6.16 Errors

OUDEA requires failures that affect identity, resolution, access, references, version selection, or Exchange completeness to be explicit. An implementation MUST NOT silently substitute another DEID, source, version, reference target, or unsupported behavior.

OUDEA Core defines error semantics at the architectural level. Exact HTTP status codes, protocol-specific error envelopes, retry behavior, and transport mappings are defined by the applicable protocol binding or implementation.

Implementations SHOULD distinguish at least DEID resolution failure, Reference target unavailable or unresolved, Exchange unavailable, authorization or access failure, unsupported capability or version, invalid public contract, and temporary infrastructure or network failure.

Where a DEID represents a complete aggregate, Exchange MUST NOT silently succeed if a required directly referenced part_of member cannot be resolved or included. Missing required members MUST cause the aggregate Exchange to fail explicitly.

Temporary infrastructure or network failure MUST NOT by itself be interpreted as a change of DEID identity, authority, lifecycle state, or canonical status. OUDEA v0.1 does not define an authoritative tombstone or withdrawn-DEID state; any exact distinction such as HTTP 404 versus 410 remains binding- or implementation-specific.

6.17 Extensions

All extensions to the OUDEA DEID contract MUST be namespaced and resolvable. An extension MAY add metadata or capabilities but MUST NOT redefine, override or contradict OUDEA Core semantics.

7. Publication Model

The OUDEA publication model separates stable governed identity from discovery projections, current infrastructure resolution, and transferred data. A publisher creates or governs a DEID under a Domain and publishes the public contracts required for other implementations to discover, resolve, understand and exchange it.

DOMAIN AUTHORITY
       |
       v
DEID + CLASS
       |
       +-- optional SCHEMA refinement
       |
       +-- REFERENCES to other DEIDs
       |
       v
AUTHORITATIVE SUPPLY
       |
       +--------> PUBLIC INDEX
       |           minimal discovery projection
       |
       +--------> FIND
       |           current resolution / access information
       |
       +--------> EXCHANGE
                   authoritative transferred data
                          |
                          v
                        DEMAND

7.1 Publication requirements

7.2 Linked DEID document

Non-normative Berlin example loaded directly from its canonical example file.

{
   "@context": "https://bytem.app/deid",
   "version": "v0.001",
   "domain": "cities.app",
   "class": "https://cities.app/class/water/DrinkingWaterQuality",
   "schema": "https://cities.app/schema/water/drinking-water-quality",
   "deid": "https://cities.app/de/be/berlin/water/drinking-water-quality",
   "label": "Berlin — Trinkwasserqualität",
   "ags": "11000000",
   "country": "DE",
   "region": "BE",
   "location": {
     "lat": 52.51767,
     "lon": 13.405538,
     "location_mode": "fixed"
   },
   "demand_room_policy": "reuse"
}

7.3 Core DEID variables

7.4 Public contracts and implementation structures

OUDEA standardizes only public structures and behavior required for independent interoperability. Internal persistence, Matrix event/state layout, bots, queues, Solr document shape, processing pipelines, access-control implementation, deployment architecture and UI remain implementation-defined.

8. Implementations

OUDEA is independent of any single implementation. bytEM™ is a reference implementation and may be documented separately. An implementation may differ internally and still target OUDEA where it implements the published public contracts and binding requirements.

Reference implementation: github.com/liberbyte/bytEM-installer

Canonical governance and trademark boundaries are documented in GOVERNANCE.md and TRADEMARKS.md.

9. Conformance

OUDEA conformance is defined against public contracts and observable behavior, not against a particular internal implementation. Use of bytEM, Liberbyte-hosted infrastructure, a particular database, bot architecture, queue, room layout or deployment model is not required for OUDEA Core conformance.

9.1 Conformance claims

An implementation claiming conformance MUST identify the OUDEA version and the conformance profile or profiles it implements. Claims SHOULD use wording such as “implements OUDEA v0.1 Core — DEID Publisher profile” or “implements OUDEA v0.1 Core — Full Implementation profile.”

OUDEA v0.1 does not define certification. Implementations MUST NOT use claims such as “OUDEA certified” unless a separate certification programme is explicitly established.

9.2 Core conformance profiles

OUDEA defines conformance profiles so implementations may claim conformance for the specific public roles and capabilities they implement without being required to implement the complete OUDEA architecture.

9.3 Protocol-binding conformance

OUDEA Core conformance and protocol-binding conformance are distinct. An implementation using the Matrix substrate MUST additionally satisfy the public OUDEA Matrix binding requirements applicable to its role. Binding conformance MUST NOT make private bytEM implementation structures normative.

9.4 Extensions and external semantic models

Use of an extension or external semantic model does not by itself change OUDEA Core conformance. A conforming implementation MUST preserve the OUDEA Core contract even when it does not understand an optional extension. An implementation MAY additionally declare conformance to a separately defined profile that requires particular extensions or external models.

9.5 Conformance tests

A machine-executable OUDEA conformance suite is planned for a subsequent specification version and is not a normative requirement of v0.1. The planned suite will test public contracts and observable behavior rather than bytEM internals. See EDITORIAL-NOTES.md for the implementation-verification note.

10. References

OUDEA distinguishes references required to interpret normative requirements from informative standards and architectural context. External semantic standards do not automatically become OUDEA Core dependencies merely because a DEID uses them.

10.1 Normative references

• RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels, together with RFC 8174, for the interpretation of MUST, SHOULD and MAY.
• RFC 3986 — Uniform Resource Identifier (URI): Generic Syntax, for URI syntax used by DEIDs and namespaced extensions.
• RFC 9110 — HTTP Semantics, where OUDEA v0.1 requires HTTPS-based resolution semantics.
• Matrix Specification, normative only for implementations claiming conformance to the OUDEA Matrix binding.

10.2 Informative references and compatible semantic models

• JSON Schema Draft 2020-12
• JSON-LD 1.1
• DPROD — Data Product Ontology
• DCAT 3
• PROV-O
• ODRL Information Model 2.2
• schema.org
• FAIR Principles
• Wilkinson et al. (2016), The FAIR Guiding Principles for scientific data management and stewardship
• FAIR — What FAIR is not…
• Common European data spaces
• OECD — G20 Compendium on Data Access and Sharing