minimal API coverage

[brandonopened]

proposed:

search, concepts, mappings, 'neighborhood'

openapi: 3.1.0
info:
title: EDUcore Minimum Semantic Backbone API
version: 0.1.0
description: >
Minimum API surface for the EDUcore Phase I semantic backbone MVP. This API
exposes canonical concepts, standards mappings, use cases, and graph neighborhoods
for human-facing applications, AI agents, and implementation tooling.
contact:
name: EDUcore Project
url: https://www.ed-core.org
servers:

• url: https://api.ed-core.org/v0
  description: Production placeholder
• url: http://localhost:3000/api/v0
  description: Local development

tags:

• name: Concepts
  description: Search and retrieve canonical semantic concepts.
• name: Mappings
  description: Retrieve mappings between canonical concepts and external standards.
• name: Graph
  description: Retrieve graph neighborhoods around concepts, standards, and use cases.
• name: Use Cases
  description: Retrieve structured use case models connected to concepts and standards.
• name: Health
  description: Basic service health checks.

paths:
/health:
get:
tags: [Health]
summary: Check API health
operationId: getHealth
responses:
'200':
description: API is available.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'

/concepts:
get:
tags: [Concepts]
summary: Search canonical concepts
description: >
Searches canonical concepts by label, description, alias, identifier,
related standard, or mapped term.
operationId: searchConcepts
parameters:
- name: q
in: query
required: true
description: Search query, such as learner, competency, accommodation, or credential.
schema:
type: string
minLength: 1
- name: standard
in: query
required: false
description: Optional standard filter, such as CEDS, CASE, CTDL, JEDx, LIF, or HR-Open-Skills.
schema:
type: string
- name: domain
in: query
required: false
description: Optional domain filter.
schema:
$ref: '#/components/schemas/Domain'
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
responses:
'200':
description: Matching canonical concepts.
content:
application/json:
schema:
$ref: '#/components/schemas/ConceptSearchResponse'

/concepts/{conceptId}:
get:
tags: [Concepts]
summary: Retrieve a canonical concept
description: Retrieves a canonical concept, including definitions, provenance, standards references, and governance metadata.
operationId: getConcept
parameters:
- $ref: '#/components/parameters/ConceptId'
- name: format
in: query
required: false
description: Response serialization format.
schema:
type: string
enum: [json, jsonld]
default: json
responses:
'200':
description: Canonical concept found.
content:
application/json:
schema:
$ref: '#/components/schemas/Concept'
application/ld+json:
schema:
$ref: '#/components/schemas/ConceptJsonLd'
'404':
$ref: '#/components/responses/NotFound'

/concepts/{conceptId}/mappings:
get:
tags: [Mappings]
summary: Retrieve mappings for a canonical concept
description: >
Retrieves mappings from an EDUcore canonical concept to external standards,
vocabularies, object models, schemas, and APIs.
operationId: getConceptMappings
parameters:
- $ref: '#/components/parameters/ConceptId'
- name: standard
in: query
required: false
description: Optional standard filter.
schema:
type: string
- name: status
in: query
required: false
description: Optional mapping governance status filter.
schema:
$ref: '#/components/schemas/MappingStatus'
- name: mappingType
in: query
required: false
schema:
$ref: '#/components/schemas/MappingType'
responses:
'200':
description: Concept mappings.
content:
application/json:
schema:
$ref: '#/components/schemas/MappingResponse'
'404':
$ref: '#/components/responses/NotFound'

/graph/{nodeId}:
get:
tags: [Graph]
summary: Retrieve graph neighborhood
description: >
Retrieves a bounded graph neighborhood around a concept, standard, mapping,
use case, or implementation artifact.
operationId: getGraphNeighborhood
parameters:
- name: nodeId
in: path
required: true
description: URI-safe identifier for a graph node.
schema:
type: string
- name: depth
in: query
required: false
description: Number of relationship hops to traverse.
schema:
type: integer
minimum: 1
maximum: 3
default: 1
- name: relationshipType
in: query
required: false
description: Optional relationship type filter.
schema:
type: string
- name: includeDeprecated
in: query
required: false
schema:
type: boolean
default: false
responses:
'200':
description: Graph neighborhood.
content:
application/json:
schema:
$ref: '#/components/schemas/GraphResponse'
'404':
$ref: '#/components/responses/NotFound'

/usecases:
get:
tags: [Use Cases]
summary: Search structured use cases
description: Searches use cases by topic, actor, standard, domain, value driver, or related concept.
operationId: searchUseCases
parameters:
- name: q
in: query
required: false
schema:
type: string
- name: domain
in: query
required: false
schema:
$ref: '#/components/schemas/Domain'
- name: standard
in: query
required: false
schema:
type: string
- name: phase
in: query
required: false
schema:
type: string
enum: [phase-1, phase-2, phase-3, phase-4]
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
responses:
'200':
description: Matching use cases.
content:
application/json:
schema:
$ref: '#/components/schemas/UseCaseSearchResponse'

/usecases/{useCaseId}:
get:
tags: [Use Cases]
summary: Retrieve a structured use case
operationId: getUseCase
parameters:
- name: useCaseId
in: path
required: true
schema:
type: string
responses:
'200':
description: Structured use case model.
content:
application/json:
schema:
$ref: '#/components/schemas/UseCase'
'404':
$ref: '#/components/responses/NotFound'

components:
parameters:
ConceptId:
name: conceptId
in: path
required: true
description: URI-safe canonical concept identifier.
schema:
type: string

responses:
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'

schemas:
HealthResponse:
type: object
required: [status, version]
properties:
status:
type: string
enum: [ok]
version:
type: string
timestamp:
type: string
format: date-time

Domain:
  type: string
  enum:
    - early-childhood
    - k12
    - postsecondary
    - workforce
    - credentialing
    - assessment
    - special-education
    - learner-records
    - cross-domain

ConceptSearchResponse:
  type: object
  required: [results, pagination]
  properties:
    results:
      type: array
      items:
        $ref: '#/components/schemas/ConceptSummary'
    pagination:
      $ref: '#/components/schemas/Pagination'

ConceptSummary:
  type: object
  required: [id, uri, label]
  properties:
    id:
      type: string
    uri:
      type: string
      format: uri
    label:
      type: string
    definition:
      type: string
    domain:
      $ref: '#/components/schemas/Domain'
    standards:
      type: array
      items:
        type: string
    mappingCount:
      type: integer
      minimum: 0

Concept:
  allOf:
    - $ref: '#/components/schemas/ConceptSummary'
    - type: object
      properties:
        aliases:
          type: array
          items:
            type: string
        sourceReferences:
          type: array
          items:
            $ref: '#/components/schemas/SourceReference'
        governance:
          $ref: '#/components/schemas/GovernanceMetadata'
        relatedConcepts:
          type: array
          items:
            $ref: '#/components/schemas/RelatedConcept'
        jsonLdContext:
          type: object
          additionalProperties: true

ConceptJsonLd:
  type: object
  additionalProperties: true
  examples:
    - '@context':
        educore: https://data.ed-core.org/ns#
        skos: http://www.w3.org/2004/02/skos/core#
      '@id': https://data.ed-core.org/concept/learner-competency
      '@type': educore:CanonicalConcept
      skos:prefLabel: Learner competency

SourceReference:
  type: object
  required: [standard, identifier]
  properties:
    standard:
      type: string
      examples: [CEDS]
    identifier:
      type: string
    uri:
      type: string
      format: uri
    version:
      type: string
    sourceStatus:
      type: string
      enum: [active, draft, deprecated, superseded, unknown]

GovernanceMetadata:
  type: object
  properties:
    status:
      type: string
      enum: [draft, proposed, reviewed, approved, deprecated]
    createdBy:
      type: string
    reviewedBy:
      type: string
    approvedBy:
      type: string
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time
    effectiveDate:
      type: string
      format: date
    confidence:
      type: number
      minimum: 0
      maximum: 1
    rationale:
      type: string

RelatedConcept:
  type: object
  required: [id, relationshipType]
  properties:
    id:
      type: string
    uri:
      type: string
      format: uri
    label:
      type: string
    relationshipType:
      type: string
      examples: [broaderThan, narrowerThan, relatedTo, partOf, equivalentTo]

MappingResponse:
  type: object
  required: [conceptId, mappings]
  properties:
    conceptId:
      type: string
    mappings:
      type: array
      items:
        $ref: '#/components/schemas/Mapping'

Mapping:
  type: object
  required: [id, sourceConceptId, targetStandard, targetIdentifier, mappingType, status]
  properties:
    id:
      type: string
    sourceConceptId:
      type: string
    sourceConceptUri:
      type: string
      format: uri
    targetStandard:
      type: string
      examples: [CEDS, CASE, CTDL, JEDx, LIF, HR-Open-Skills]
    targetIdentifier:
      type: string
    targetUri:
      type: string
      format: uri
    targetLabel:
      type: string
    mappingType:
      $ref: '#/components/schemas/MappingType'
    status:
      $ref: '#/components/schemas/MappingStatus'
    confidence:
      type: number
      minimum: 0
      maximum: 1
    deterministic:
      type: boolean
    rationale:
      type: string
    provenance:
      $ref: '#/components/schemas/Provenance'

MappingType:
  type: string
  enum:
    - exactMatch
    - closeMatch
    - broadMatch
    - narrowMatch
    - relatedMatch
    - transformationRequired
    - noMatch

MappingStatus:
  type: string
  enum:
    - ai-suggested
    - proposed
    - reviewed
    - approved
    - rejected
    - deprecated

Provenance:
  type: object
  properties:
    source:
      type: string
    sourceUri:
      type: string
      format: uri
    method:
      type: string
      enum: [manual, ai-assisted, imported, inferred, standards-body-approved]
    generatedBy:
      type: string
    reviewedBy:
      type: string
    timestamp:
      type: string
      format: date-time

GraphResponse:
  type: object
  required: [nodes, edges]
  properties:
    nodes:
      type: array
      items:
        $ref: '#/components/schemas/GraphNode'
    edges:
      type: array
      items:
        $ref: '#/components/schemas/GraphEdge'

GraphNode:
  type: object
  required: [id, type, label]
  properties:
    id:
      type: string
    uri:
      type: string
      format: uri
    type:
      type: string
      enum: [concept, standard, mapping, useCase, artifact, organization]
    label:
      type: string
    metadata:
      type: object
      additionalProperties: true

GraphEdge:
  type: object
  required: [source, target, relationshipType]
  properties:
    source:
      type: string
    target:
      type: string
    relationshipType:
      type: string
    metadata:
      type: object
      additionalProperties: true

UseCaseSearchResponse:
  type: object
  required: [results]
  properties:
    results:
      type: array
      items:
        $ref: '#/components/schemas/UseCaseSummary'

UseCaseSummary:
  type: object
  required: [id, title]
  properties:
    id:
      type: string
    title:
      type: string
    domain:
      $ref: '#/components/schemas/Domain'
    valueDriver:
      type: string
    standards:
      type: array
      items:
        type: string
    phase:
      type: string
    status:
      type: string
      enum: [draft, active, prioritized, archived]

UseCase:
  allOf:
    - $ref: '#/components/schemas/UseCaseSummary'
    - type: object
      properties:
        description:
          type: string
        actors:
          type: array
          items:
            $ref: '#/components/schemas/Actor'
        businessLayer:
          $ref: '#/components/schemas/BusinessLayer'
        semanticLayer:
          $ref: '#/components/schemas/SemanticLayer'
        transportLayer:
          $ref: '#/components/schemas/TransportLayer'
        governanceLayer:
          $ref: '#/components/schemas/UseCaseGovernanceLayer'
        aiLayer:
          $ref: '#/components/schemas/AiLayer'

Actor:
  type: object
  required: [name, role]
  properties:
    name:
      type: string
    role:
      type: string
    organizationType:
      type: string

BusinessLayer:
  type: object
  properties:
    problemStatement:
      type: string
    valueDriver:
      type: string
    successCriteria:
      type: array
      items:
        type: string

SemanticLayer:
  type: object
  properties:
    canonicalConceptIds:
      type: array
      items:
        type: string
    standards:
      type: array
      items:
        type: string
    requiredMappings:
      type: array
      items:
        type: string

TransportLayer:
  type: object
  properties:
    inputObjects:
      type: array
      items:
        type: string
    outputObjects:
      type: array
      items:
        type: string
    apiPatterns:
      type: array
      items:
        type: string

UseCaseGovernanceLayer:
  type: object
  properties:
    privacyConsiderations:
      type: array
      items:
        type: string
    provenanceRequirements:
      type: array
      items:
        type: string
    humanReviewRequired:
      type: boolean
    auditLoggingRequired:
      type: boolean

AiLayer:
  type: object
  properties:
    allowedAgentActions:
      type: array
      items:
        type: string
    prohibitedAgentActions:
      type: array
      items:
        type: string
    uncertaintyHandling:
      type: string

Pagination:
  type: object
  required: [limit, offset, total]
  properties:
    limit:
      type: integer
    offset:
      type: integer
    total:
      type: integer

ErrorResponse:
  type: object
  required: [error]
  properties:
    error:
      type: string
    message:
      type: string
    traceId:
      type: string