{
  "$id": "https://standards.apievangelist.com/layers.json",
  "name": "API Evangelist data model layer vocabulary",
  "description": "What KIND of artifact a data model standard is. An agent holding a task and a domain resolves to a layer, and from the layer to a shortlist of standards, without reading prose.",
  "sibling": "https://tools.apievangelist.com/roles.json",
  "corpus": "https://standards.apievangelist.com/models.json",
  "updated": "2026-08-11",
  "how_to_use": "Two standards can describe the same domain and still be unusable for your task, because they sit at different layers. Pick the layer from what you are trying to DO, then filter by domain. An exchange-schema will not tell you what an entity means; an ontology will not tell you what bytes to put on the wire.",
  "layers": {
    "information-model": {
      "label": "Information Model",
      "question": "What entities exist in this domain, and how do they relate?",
      "returns": "An implementation-neutral definition of entities, attributes and relationships, meant to be mapped onto many technologies.",
      "agent_note": "Read this to LEARN a domain before you touch any wire format. It will not give you something to serialize directly — that is deliberate. When a task says 'model our claims data' rather than 'call this API', this is the layer you want. Examples: OMOP CDM, IEC CIM, NIEM, MISMO, LADM.",
      "not_this_if": "You need something you can validate a payload against today. Go to exchange-schema."
    },
    "exchange-schema": {
      "label": "Exchange Schema",
      "question": "What exactly do I put on the wire, and how do I validate what comes back?",
      "returns": "A data model expressed as messages or documents — XSD, JSON Schema, EDI segments, FHIR-style resources.",
      "agent_note": "The layer you can act on immediately. These carry a machine-readable artifact you can fetch and validate against. Most integration tasks resolve here. Check `licensing` before assuming you can retrieve it — a sold specification means the schema may not be fetchable at all. Examples: FHIR, ISO 20022, UBL, GTFS, VCF.",
      "not_this_if": "You are trying to understand what a field MEANS across systems. That is information-model or ontology-vocabulary."
    },
    "code-system": {
      "label": "Code System",
      "question": "What are the legal values for this field, and what does each one mean?",
      "returns": "Controlled vocabularies, code lists, classifications and identifier schemes.",
      "agent_note": "No domain model works without these, and they are the most likely thing in this catalog to be LICENSED rather than open — SNOMED CT, CPT, CUSIP, MedDRA and Dewey all require a licence. Always read `access` before planning to embed one. A code system you cannot redistribute will fail at deployment, not at design.",
      "not_this_if": "You need structure rather than values. Codes fill fields; they do not define them."
    },
    "ontology-vocabulary": {
      "label": "Ontology / Vocabulary",
      "question": "What do these concepts mean formally, and how can a machine reason over them?",
      "returns": "RDF/OWL/SKOS/SHACL classes, properties and axioms with resolvable URIs.",
      "agent_note": "Use when you need to RECONCILE across sources rather than move data between two known endpoints — mapping one vocabulary onto another, or inferring relationships. Resolvable URIs mean you can dereference a term to its definition, which is the one thing this layer gives you that no other does. Examples: schema.org, SKOS, Gene Ontology, CIDOC CRM, SAREF.",
      "not_this_if": "You have a fixed integration between two systems. The reasoning power is overhead you will not use."
    },
    "metadata-model": {
      "label": "Metadata Model",
      "question": "How do I describe this dataset, record or object so someone else can find and trust it?",
      "returns": "Models for discovery, provenance, preservation and cataloguing — about the data rather than the domain.",
      "agent_note": "The layer that answers 'where did this come from and can I rely on it'. Increasingly the layer that matters for AI training-data questions. Examples: Dublin Core, DCAT, DataCite, PROV-O, Croissant, RO-Crate.",
      "not_this_if": "You want the content of the data itself, not a description of it."
    },
    "reference-architecture": {
      "label": "Reference Architecture",
      "question": "How does a whole domain fit together, and where does my system sit in it?",
      "returns": "A domain data model bundled inside a broader architectural or process framework.",
      "agent_note": "The broadest and least directly actionable layer. Read for orientation and for the vocabulary a sector uses about itself; do not expect a schema to validate against. Examples: BIAN, ISA-95, GSBPM, IT4IT.",
      "not_this_if": "You need anything concrete. Almost always you want a narrower layer."
    }
  },
  "access_postures": {
    "description": "How much it costs to read and implement a standard. Reported independently of the modernity band, because a standard can be technically current and still be closed.",
    "open": "Free to read and build on.",
    "gated": "Full specification or artifacts require joining the body.",
    "enclosed": "The specification is sold, or the content itself is licensed per seat. A structural barrier to implementation, independent of technical quality.",
    "unknown": "Not established. NEVER treat this as open — it means unresearched, not free."
  },
  "modernity_bands": {
    "description": "How current a standard is in how it is expressed, published, governed and paid for. A SEPARATE measure from the API Evangelist Kin Score, which rates API providers rather than standards.",
    "warning": "Low is not bad. EDIFACT and X12 score low here and move an enormous share of world trade. This measures era and openness, not worth or correctness.",
    "current": "Machine-readable, openly published, developed in public, versioned legibly.",
    "modernizing": "A real modernization underway — usually an XML-era core with a maintained JSON or RDF binding.",
    "legacy": "Load-bearing, and expressed in the idiom of the decade it was written in.",
    "closed_era": "Little for a new implementer to work from — no machine-readable form, no public process, no legible change record.",
    "unrated": "The profiler could not read enough of the standard to place it in a band. This is a limit of our evidence, NOT a finding against the standard. Do not treat an unrated standard as a low-scoring one."
  }
}