OKF Explorer OKF Explorer documentation

OKF Standards Crosswalk (DCAT-AP / OpenAPI)

This repository's OKF record contract (okf-bundle-authoring.md) is deliberately plain-English Markdown and JSON, not RDF or an executable API description. That is the right choice for authoring and for the Explorer, but it means every bundle re-derives field names from scratch. This page is the standing crosswalk between the OKF fields already in use (see the api-records/*.md Metadata blocks in uk-government-apis/) and the two external standards that already cover this domain:

Use this page when designing a new bundle's frontmatter or generator, when deciding what a new field should be called, or when someone outside this repository asks "what does licence basis mean in DCAT/OpenAPI terms?"

Status: standards-alignable, not standards-conformant

Nothing here changes today's output format. uk-government-apis/api-records/*.md and the okf-explorer.json shards stay Markdown/JSON. Full DCAT-AP conformance requires an RDF serialisation (Turtle/JSON-LD) with DCAT-AP's cardinality rules (for example dcat:endpointURL is mandatory, 1..n); full OpenAPI conformance requires a complete openapi document per API version. This repository does neither yet. What this crosswalk guarantees instead is that every OKF field already has a named, correct target in both standards, so a future exporter (or a hand-written report, like the OS inventory produced from this pack) can translate without guessing. Treat "DCAT-alignable" and "OpenAPI-alignable" as the honest claim; do not describe a bundle as DCAT-AP or OpenAPI conformant unless an RDF or openapi.yaml artefact actually ships alongside it.

Repository implementation status

The standards are now localised in the OKF source tree as browser-compatible Markdown concept pages:

scripts/build_uk_government_api_okf.py applies this crosswalk to the uk-government-apis large-corpus bundle by emitting, for each API/data record:

The generated descriptor also exposes okf-standards-crosswalk.v1, local and official standard references, and aggregate missing-field counts in data/analysis/overview.json. These fields are intentionally compact per record; the full field semantics live here and in the local standards pages.

API-bundle gap analysis

The current UK Government APIs OKF is much closer to a standards-aligned catalogue than to executable API specification output. That is the right state for an observed multi-source pack, but it leaves clear gaps:

Export target Current coverage Remaining gap
DCAT dcat:DataService API products, provider-native APIs and data-access endpoints are mapped to dcat:DataService; endpoint/documentation/publisher/licence fields are preserved when observed. A DCAT-AP-conformant RDF exporter is not yet implemented; some records still lack explicit dcat:endpointURL, dcat:endpointDescription, licence or publisher evidence.
DCAT dcat:Dataset data.gov.uk and ONS data products map to dcat:Dataset; provider and licence inference is recorded with basis and confidence. Dataset distributions, themes and provenance need richer source-specific export rules before claiming DCAT-AP profile conformance.
OpenAPI service stub API products and data endpoints can produce an info, servers and externalDocs skeleton where endpoint metadata exists. Most harvested sources do not expose complete methods, paths, parameters, responses, schemas, examples or security flows, so generated OpenAPI is a stub unless a contract parser enriches it.
OpenAPI operation fragment OS and ONS operation-like records can be represented as operation fragments. HTTP method, operationId, parameters, request/response schemas and error models are often missing and must not be invented.
OpenAPI security schemes access_model now maps to apiKey, oauth2, none, metadata-only or unknown. The location/name of API keys, OAuth flow, scopes, token URLs and sender-constrained-token requirements need provider-specific contract parsing.
DQV quality annotations OKF metadata-quality dimensions are named and explained in the UI. No DQV RDF is emitted yet, and quality percentages remain catalogue-completeness signals rather than assurance metrics.
PROV provenance Records and relationships carry source adapter, source URL, confidence and observed timestamp. A full PROV activity graph for each adapter run is not emitted yet.

For all API-related bundles, treat these gaps as build requirements rather than documentation caveats. A bundle can be standards-alignable at publication time, but it should not claim DCAT-AP conformant or OpenAPI conformant until the relevant artefact is generated and validated.

Export-readiness requirements

A DCAT export for an API-like record needs, at minimum:

An OpenAPI export needs, at minimum:

If any of these fields are unavailable, the exporter should emit either a clearly labelled stub or no artefact. It must not invent method, parameter, response, schema, licence, access or security details.

Explorer terminology rules

The Explorer should prefer standards names where the standards are authoritative and retain OKF names where the standards do not have an exact concept:

Record-type crosswalk

OKF type (this repo) DCAT / DCAT-AP class OpenAPI equivalent Notes
API Product dcat:DataService info object of one API's OpenAPI document The product is the service-level description; DCAT does not separate product/version, so version state goes in dct:conformsTo / dcat:version on the same DataService.
API Operation Not a separate DCAT class — model as dcat:endpointURL + dcat:endpointDescription on the parent dcat:DataService, or as a dcat:Distribution when the operation returns a static extract paths.<path>.<method> operation object DCAT has no first-class "operation" concept; this is a known gap the repo already documents in sources/UK-Government-API-OKF.md. Keep API Operation as an OKF-native type and only crosswalk its fields (endpoint, doc, access) upward to the parent product's DataService.
Capability Document / Contract The value of dct:conformsTo on the related dcat:DataService The openapi.yaml/WSDL/WFS capabilities document itself Do not model contracts as their own DataService; they are the standard the service conforms to.
Provider API Portal foaf:homepage / dcat:landingPage of the publisher's dcat:Catalog servers entry with no dedicated OpenAPI concept Portal pages are catalogue-level, not service-level.
Organisation dct:publisher (foaf:Agent) info.contact / info.license attribution —
Data Product / Dataset dcat:Dataset Not represented in OpenAPI (OpenAPI describes the service, not the data) dcat:servesDataset links the DataService to this.

Field crosswalk

OKF field (Metadata block / Minimum Record Contract) DCAT / DCAT-AP property OpenAPI field Notes
title dcterms:title info.title (product) / operation summary (operation) Direct mapping.
description dcterms:description info.description / operation description Direct mapping.
id / route catalogue-assigned IRI for the resource N/A (routes are an OKF/Explorer concept) DCAT wants a global IRI; the route is this repo's stable local identifier and should be treated as the local part of that IRI.
type / record_type rdf:type (see record-type table above) N/A —
Provider / Canonical provider dct:publisher info.contact —
Endpoint dcat:endpointURL servers[].url (product) or resolved {server}{path} (operation) dcat:endpointURL is DCAT-AP's one mandatory DataService property — if a bundle can only guarantee one crosswalk-ready field, make it this one.
Documentation dcat:endpointDescription externalDocs.url DCAT 3 explicitly recommends dcat:endpointDescription point at a machine- or human-readable description of the endpoint's operations and parameters — the same role externalDocs plays in OpenAPI.
Source tier / Source adapter dcterms:provenance (free text) or a prov:Activity on a dcat:CatalogRecord N/A OpenAPI has no provenance concept; this stays OKF/DCAT-only.
Confidence / Assurance status No direct DCAT property — closest is dqv:QualityAnnotation (Data Quality Vocabulary, used alongside DCAT) N/A Flag as a genuine gap rather than forcing a fit.
Contract status dcterms:conformsTo (points at the contract resource) Presence/absence of a discoverable openapi.yaml —
Licence dcterms:license info.license.name / info.license.url Direct mapping.
Licence basis / Licence confidence No DCAT property — this is OKF's own provenance-of-metadata concept N/A Keep as an OKF-native field; note it in dcterms:provenance free text if exporting.
Access model Not modelled in DCAT directly; DCAT-AP uses dcatap:availability for a different concept (distribution lifecycle, not auth) components.securitySchemes.<name>.type See the access-model table below — this is the one field where OpenAPI, not DCAT, is the authoritative vocabulary.
Tags / topics dcat:keyword / dcat:theme tags Direct mapping.
Catalogue timestamps (metadata_created, metadata_modified) dcterms:issued / dcterms:modified on dcat:CatalogRecord N/A These date the catalogue metadata record, not necessarily the dataset’s publication or latest release.
operational_metadata.update_frequency dcterms:accrualPeriodicity on dcat:Dataset N/A Populate from a canonical publisher source with provenance; do not infer it from a resource hostname.
operational_metadata.distributions dcat:distribution / dcat:Distribution API-backed access may map to servers and paths Keep complete extracts, change-only extracts and API access distinct.
operational_metadata.latest_release dcterms:issued / dcterms:modified on the relevant dcat:Distribution info.version only when the publisher identifies it as an API version A dynamic marker tells Explorer to consult the canonical source; it is not itself a release date.
Generated/observed timestamps prov:generatedAtTime / prov:endedAtTime on the harvest activity N/A Keep harvest time separate from catalogue and dataset dates.

Access model → OpenAPI securityScheme.type

OKF access_model value OpenAPI securitySchemes.<name>.type Notes
api-key apiKey Set in/name to header/query per provider docs when known; this repo does not currently record that level of detail.
oauth2 oauth2 Record the flow (authorizationCode, clientCredentials, etc.) once known; OS's OS OAuth 2 API record is the flow endpoint itself and should be the tokenUrl of an oauth2 scheme.
unknown Omit security/securitySchemes and say so explicitly This is a metadata gap, not evidence the API is open. Per okf-bundle-authoring.md's metadata-repair rules, never silently upgrade unknown to none.
(not yet used) none Empty security: [] Reserve this for a source that explicitly documents no authentication, not for missing data.

Worked example: OS Places API postcode Operation

This is the record from uk-government-apis/api-records/ordnance-survey-operation-https-api-os-uk-search-places-v1-postcode.md.

Existing OKF metadata (unchanged):

- Type: API Operation
- Endpoint: https://api.os.uk/search/places/v1/postcode
- Documentation: https://osdatahub.os.uk/docs/places/overview
- Access model: api-key
- Licence: Ordnance Survey licence required
- Licence basis: provider-terms-inferred

Equivalent DCAT (DCAT 3 Turtle, on the parent OS Places API DataService, per the record-type table above — operations roll up rather than each getting their own DataService):

<https://api.os.uk/search/places/v1>
  a dcat:DataService ;
  dcterms:title "OS Places API" ;
  dcat:endpointURL <https://api.os.uk/search/places/v1> ;
  dcat:endpointDescription <https://osdatahub.os.uk/docs/places/overview> ;
  dcterms:license <https://www.ordnancesurvey.co.uk/licensing> ;
  dcterms:publisher <https://www.ordnancesurvey.co.uk/> .

Equivalent OpenAPI path-item fragment (operation-level):

paths:
  /search/places/v1/postcode:
    get:
      summary: OS Places API postcode Operation
      description: >-
        A search based on a property's postcode.
      externalDocs:
        url: https://osdatahub.os.uk/docs/places/overview
      security:
        - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: key

The apiKey in/name values above are illustrative — this repository does not currently harvest that level of detail and a generator should not invent it; leave in/name unset (or add a documented unknown placeholder) until a source declares it.

How to use this when building a bundle

  1. Start from okf-bundle-authoring.md's Minimum Record Contract — it is still the canonical authoring reference.
  2. When you need to name a new field, check the field crosswalk table first. Reusing a name that already has a DCAT/OpenAPI target keeps the bundle federatable; inventing a new name for something already in this table is a documentation debt.
  3. If a concept genuinely has no DCAT or OpenAPI equivalent (confidence, licence basis, quality bands are the known examples), keep it OKF-native and say so here rather than forcing a bad fit.
  4. If a bundle ever ships an RDF or openapi.yaml export, it should be generated from these mappings, and the export's conformance claim should be checked against the "standards-alignable, not standards-conformant" section above before it is described as DCAT-AP or OpenAPI conformant.

Sources