ai-catalog entries have a fixed set of core fields. To let new artifact types define their own typed, queryable attributes without colliding with core fields or with each other, a catalog MAY declare namespace prefixes using @context.

This is JSON-LD-inspired, but intentionally limited. ai-catalog processors are not required to process catalogs as JSON-LD. Here, @context only binds prefixes for extension keys such as okf:type or canvas:artifactKind.

@context maps prefixes to absolute namespace IRIs. It MAY appear at catalog level and/or entry level. Entry-level context MAY add prefixes, but MUST NOT redefine a prefix already declared at catalog level.

Core terms are namespace-free. There is no @vocab. Unprefixed keys such as identifier, type, url, displayName, description, tags, and capabilities are the closed, reserved core set. An unprefixed key outside the core set is invalid.

Extension fields MUST use a prefixed key of the form prefix:term, where the prefix is declared in the in-scope @context. Extension values MAY be any JSON value unless constrained by the namespace’s schema.

ARD search queries that reference namespaced fields MUST also declare the prefixes they use in an in-scope @context, unless the query profile defines them out of band.

A namespace SHOULD publish documentation or a schema for its terms. Consumers MUST NOT reject an entry solely because it contains an extension field with an unrecognized prefix. Systems that transform or republish entries SHOULD preserve unrecognized extension fields unless explicitly configured otherwise.

Entries with no @context and no extension fields are valid and unchanged.

Example: OKF dataset

OKF has its own type field, which would collide with the ai-catalog core type. The namespace resolves the collision.

{  
  "specVersion": "1.0",  
  "@context": {  
    "okf": "https://openknowledgeformat.org/ns#"  
  },  
  "entries": [  
    {  
      "identifier": "urn:air:treasury.gov:okf:fiscaldata",  
      "type": "text/vnd.okf+markdown",  
      "url": "https://example.org/sources/treasury-fiscaldata.md",  
      "displayName": "US Treasury — FiscalData",  
      "tags": [  
        "finance",  
        "treasury"  
      ],  
      "okf:type": "Financial Dataset",  
      "okf:taxonomy": "us-gaap",  
      "okf:periodType": "instant"  
    }  
  ]  
}

An ARD search query can refer to namespaced fields by their serialized key, but must declare the namespace prefix it uses:

{ "@context": { "okf": "https://openknowledgeformat.org/ns#" },   
  "query": "official fiscal data",   
  "filter": { "okf:type": ["Financial Dataset"], "okf:taxonomy": "us-gaap" }   
}

Discovery services MAY additionally expand prefixed keys to namespace IRIs for internal indexing, but clients MUST NOT rely on such normalization unless advertised by the service.

Example: Copilot Canvas extension

Github Copilot Canvas reuses core capabilities and namespaces only Canvas-specific fields.

{ "specVersion": "1.0",   
  "@context": { "canvas": "https://github.com/copilot/ns/canvas#" },   
  "entries": [{ "identifier": "urn:air:github.com:canvas:triage-board",   
                "type":   "application/vnd.github.canvas-extension",   
                "url": "https://github.com/acme/.github/extensions/triage-board",   
                "displayName": "Issue Triage Board",   
                "capabilities": ["get_board", "add_card", "move_card"],   
                "canvas:scope": "project",   
                "canvas:artifactKind": "kanban" }]   
}

Namespacing keeps the ai-catalog core small while allowing communities to define their own queryable attributes without central coordination.