specifications-vocabulary.yml

vocabulary: "1.0.0"

info:
  provider: API Specifications
  description: >-
    Vocabulary taxonomy for the meta-layer of API specification languages —
    HTTP request/response specs, event-driven specs, service interface
    definition languages, schema languages, RPC protocols, and vendor-defined
    specs. This vocabulary defines the cross-cutting terminology (spec,
    version, dialect, schema, interface, contract, profile) used to describe
    every individual specification profiled in the API Evangelist network.
  created: "2026-05-22"
  modified: "2026-05-22"

operational:
  specifications:
    - name: OpenAPI Specification
      namespace: openapi
      category: HTTP Request/Response
      version: "3.1.0"
      governingBody: OpenAPI Initiative
      parent: Linux Foundation
      license: Apache-2.0
      status: active
    - name: AsyncAPI Specification
      namespace: asyncapi
      category: Event-Driven
      version: "3.0.0"
      governingBody: AsyncAPI Initiative
      parent: Linux Foundation
      license: Apache-2.0
      status: active
    - name: JSON Schema
      namespace: json-schema
      category: Schema
      version: "Draft 2020-12"
      governingBody: JSON Schema
      license: BSD-3-Clause
      status: active
    - name: JSON Structure
      namespace: json-structure
      category: Schema
      version: "Core v0"
      governingBody: JSON Structure Working Group
      license: Apache-2.0
      status: emerging
    - name: GraphQL SDL
      namespace: graphql
      category: Service Interface (IDL)
      version: "October 2021"
      governingBody: GraphQL Foundation
      parent: Linux Foundation
      license: OWFa-1.0
      status: active
    - name: gRPC / Protobuf
      namespace: grpc
      category: RPC Protocol
      version: "proto3"
      governingBody: CNCF / Google
      parent: Linux Foundation
      license: Apache-2.0
      status: active
    - name: Smithy
      namespace: smithy
      category: Service Interface (IDL)
      version: "2.0"
      governingBody: Smithy-Lang (AWS)
      license: Apache-2.0
      status: active
    - name: TypeSpec
      namespace: typespec
      category: Service Interface (IDL)
      version: "1.x"
      governingBody: Microsoft
      license: MIT
      status: active
    - name: RAML
      namespace: raml
      category: HTTP Request/Response
      version: "1.0"
      governingBody: RAML Workgroup (Mulesoft/Salesforce)
      license: Apache-2.0
      status: legacy
    - name: API Blueprint
      namespace: api-blueprint
      category: HTTP Request/Response
      version: "1A r9"
      governingBody: Apiary / Oracle
      license: MIT
      status: historical
    - name: WSDL / SOAP
      namespace: wsdl
      category: Service Interface (IDL)
      version: "WSDL 2.0 / SOAP 1.2"
      governingBody: W3C
      license: W3C-Document
      status: historical
    - name: JSON-RPC 2.0
      namespace: json-rpc
      category: RPC Protocol
      version: "2.0"
      governingBody: JSON-RPC Working Group
      license: CC0-1.0
      status: active
    - name: Tinybird API Spec
      namespace: tinybird
      category: Vendor-Defined
      version: "vendor-current"
      governingBody: Tinybird
      license: MIT
      status: active

  resources:
    - name: Specification
      description: A named language for describing API behavior, schema, or interface.
      actions: [list, reference, compare, catalog]
    - name: Version
      description: A specific dated/numbered revision of a specification.
      actions: [list, reference]
    - name: Dialect
      description: A schema dialect or draft (e.g. JSON Schema Draft 2020-12, OpenAPI 3.0 Schema Object).
      actions: [reference, validate]
    - name: Schema
      description: A structural definition of data shapes, embedded in or standalone from a spec.
      actions: [author, validate, reference]
    - name: Interface
      description: A described service surface — endpoints, operations, channels, RPC methods.
      actions: [author, describe, generate]
    - name: Contract
      description: An agreed-upon, often versioned, machine-readable description of API behavior.
      actions: [author, govern, version]
    - name: Profile
      description: A constrained subset or conformance class of a specification.
      actions: [reference, validate]
    - name: GoverningBody
      description: The organization or working group that maintains the specification.
      actions: [reference]
    - name: ToolingEcosystem
      description: The set of tools, SDKs, linters, and generators around a specification.
      actions: [list, reference]

  actions:
    - verb: author
      description: Write or maintain a specification document or schema.
      pattern: write
    - verb: validate
      description: Verify that a document conforms to a specification or schema dialect.
      pattern: read
    - verb: reference
      description: Look up a specification, version, or term.
      pattern: read
    - verb: catalog
      description: Inventory specifications and their properties across an organization or domain.
      pattern: read
    - verb: govern
      description: Apply organizational rules and linting to spec artifacts.
      pattern: write
    - verb: compare
      description: Contrast two specifications across category, transport, or feature axes.
      pattern: read
    - verb: generate
      description: Emit code, docs, mocks, or alternate spec formats from a source spec.
      pattern: write

  schemas:
    core:
      - SpecificationRecord
      - GoverningBody
      - License
      - SpecificationVersion

  parameters:
    identifiers:
      - name: specificationId
        description: Stable identifier for a specification (e.g. openapi, asyncapi).
      - name: version
        description: Specification version string.
      - name: governingBodyId
        description: Identifier of the governing body.
    filters:
      - name: category
        description: Category filter (HTTP Request/Response, Event-Driven, IDL, Schema, RPC, Vendor-Defined).
      - name: status
        description: Lifecycle status filter (active, maintenance, legacy, historical, emerging).
      - name: license
        description: SPDX license identifier filter.
      - name: parent
        description: Umbrella foundation filter (e.g. Linux Foundation, W3C, CNCF).

  enums:
    categories:
      - HTTP Request/Response
      - Event-Driven
      - Service Interface (IDL)
      - Schema
      - RPC Protocol
      - Vendor-Defined
    statuses:
      - active
      - maintenance
      - legacy
      - historical
      - emerging
    formats:
      - YAML
      - JSON
      - Markdown
      - XML
      - DSL
      - Protobuf
      - Multiple
    transports:
      - HTTP/1.1
      - HTTP/2
      - HTTP/3
      - WebSocket
      - Kafka
      - AMQP
      - MQTT
      - NATS
      - SNS/SQS
      - TCP
      - gRPC
      - XML/SOAP
      - Multiple
      - N/A
    governingBodies:
      - OpenAPI Initiative
      - AsyncAPI Initiative
      - JSON Schema
      - JSON Structure Working Group
      - GraphQL Foundation
      - Cloud Native Computing Foundation
      - Smithy-Lang (AWS)
      - Microsoft
      - RAML Workgroup
      - Apiary / Oracle
      - W3C
      - JSON-RPC Working Group
      - Tinybird

  authentication:
    schemes: []
    notes: API specifications are public documents — no authentication required.

capability:
  workflows:
    - name: Specification Selection
      description: Choosing the right specification language(s) for a new API based on transport, audience, and tooling.
      specifications: [OpenAPI Specification, AsyncAPI Specification, gRPC / Protobuf, GraphQL SDL, Smithy, TypeSpec]
      personas: [API Architect, API Designer, Platform Engineer]
    - name: Multi-Format Generation
      description: Authoring in a high-level IDL (TypeSpec, Smithy) and emitting OpenAPI, JSON Schema, and Protobuf.
      specifications: [TypeSpec, Smithy, OpenAPI Specification, JSON Schema]
      personas: [API Designer, Platform Engineer]
    - name: Event-Driven Contract Design
      description: Defining channels, operations, and messages using AsyncAPI alongside Avro/Protobuf schemas.
      specifications: [AsyncAPI Specification, gRPC / Protobuf, JSON Schema]
      personas: [Event Architect, Platform Engineer]
    - name: Specification Governance
      description: Applying linting and conventions across OpenAPI, AsyncAPI, and JSON Schema artifacts.
      specifications: [OpenAPI Specification, AsyncAPI Specification, JSON Schema]
      personas: [API Governance Lead, Platform Engineer]
    - name: Legacy Modernization
      description: Migrating WSDL/SOAP and RAML interfaces to modern OpenAPI- or Smithy-described services.
      specifications: [WSDL / SOAP, RAML, OpenAPI Specification, Smithy]
      personas: [API Architect, Platform Engineer]
    - name: Vendor Spec Reconciliation
      description: Mapping vendor-defined formats (e.g. Tinybird) to OpenAPI for consistent governance and SDK generation.
      specifications: [Tinybird API Spec, OpenAPI Specification]
      personas: [API Designer, Platform Engineer]

  personas:
    - id: api-architect
      name: API Architect
      description: Defines the specification strategy and contract patterns across an organization.
      workflows: [Specification Selection, Legacy Modernization]
    - id: api-designer
      name: API Designer
      description: Authors specification artifacts (OpenAPI, AsyncAPI, TypeSpec, Smithy).
      workflows: [Specification Selection, Multi-Format Generation, Vendor Spec Reconciliation]
    - id: platform-engineer
      name: Platform Engineer
      description: Builds and operates the tooling that consumes specifications (generators, mocks, gateways).
      workflows: [Multi-Format Generation, Event-Driven Contract Design, Specification Governance, Legacy Modernization, Vendor Spec Reconciliation]
    - id: api-governance-lead
      name: API Governance Lead
      description: Owns linting, conventions, and lifecycle rules across the spec inventory.
      workflows: [Specification Governance]
    - id: event-architect
      name: Event Architect
      description: Designs event-driven architectures and their AsyncAPI/schema contracts.
      workflows: [Event-Driven Contract Design]

  domains:
    - name: HTTP Specifications
      description: Languages for describing synchronous HTTP REST APIs.
      specifications: [OpenAPI Specification, RAML, API Blueprint]
    - name: Event-Driven Specifications
      description: Languages for describing message-driven and event-driven APIs.
      specifications: [AsyncAPI Specification]
    - name: Service Interface Definition Languages
      description: Protocol-agnostic IDLs that emit clients, servers, and other specs.
      specifications: [GraphQL SDL, gRPC / Protobuf, Smithy, TypeSpec, WSDL / SOAP]
    - name: Schema Languages
      description: Languages for describing data shapes independent of transport.
      specifications: [JSON Schema, JSON Structure]
    - name: RPC Protocols
      description: Specifications for remote procedure call protocols.
      specifications: [gRPC / Protobuf, JSON-RPC 2.0]
    - name: Vendor-Defined Specifications
      description: Vendor-owned specification formats that govern specific products.
      specifications: [Tinybird API Spec]

crossReference:
  - resource: Specification
    operations: [catalog, reference, compare]
    specifications: [OpenAPI Specification, AsyncAPI Specification, JSON Schema, JSON Structure, GraphQL SDL, gRPC / Protobuf, Smithy, TypeSpec, RAML, API Blueprint, WSDL / SOAP, JSON-RPC 2.0, Tinybird API Spec]
    personas: [API Architect, API Designer, API Governance Lead]
  - resource: Schema
    operations: [author, validate, reference]
    specifications: [JSON Schema, JSON Structure, OpenAPI Specification, AsyncAPI Specification, gRPC / Protobuf]
    personas: [API Designer, Platform Engineer]
  - resource: Interface
    operations: [author, describe, generate]
    specifications: [GraphQL SDL, gRPC / Protobuf, Smithy, TypeSpec, OpenAPI Specification, WSDL / SOAP]
    personas: [API Designer, Platform Engineer]
  - resource: Contract
    operations: [govern, version]
    specifications: [OpenAPI Specification, AsyncAPI Specification, Smithy, TypeSpec]
    personas: [API Governance Lead, API Architect]