{
  "components": {
    "schemas": {
      "CompactProfile": {
        "additionalProperties": false,
        "description": "A compact, metadata-only profile summary used in search results and listings.",
        "properties": {
          "id": {
            "pattern": "^prof_[0-9a-f]{32}$",
            "type": "string"
          },
          "kind": {
            "oneOf": [
              {
                "additionalProperties": false,
                "properties": {
                  "controlled": {
                    "type": "boolean"
                  },
                  "value": {
                    "type": "string"
                  }
                },
                "required": [
                  "controlled",
                  "value"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "models": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "ompVersion": {
            "type": [
              "string",
              "null"
            ]
          },
          "owner": {
            "type": [
              "string",
              "null"
            ]
          },
          "providers": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "revision": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string"
          },
          "structural": {
            "enum": [
              "valid",
              "invalid"
            ],
            "type": "string"
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "models",
          "providers",
          "source",
          "structural",
          "updatedAt",
          "url"
        ],
        "type": "object"
      },
      "Error": {
        "$id": "https://oompf.run/schemas/error.json",
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "description": "Stable JSON error envelope returned by every non-2xx OOMPF API response.",
        "examples": [
          {
            "error": {
              "code": "not_found",
              "message": "No indexed profile with id \"prof_0000\"."
            }
          },
          {
            "error": {
              "code": "validation_failed",
              "details": [
                "modelRoles must be a mapping of role to model."
              ],
              "message": "The profile is not a structurally valid OMP artifact."
            }
          }
        ],
        "properties": {
          "error": {
            "additionalProperties": false,
            "properties": {
              "code": {
                "description": "Stable machine-readable error code.",
                "enum": [
                  "invalid_source",
                  "source_not_found",
                  "ambiguous_source",
                  "source_unreachable",
                  "validation_failed",
                  "blocking_secrets",
                  "not_found",
                  "server_misconfigured",
                  "internal_error"
                ],
                "type": "string"
              },
              "details": {
                "description": "Optional actionable specifics. Never contains a secret value.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "message": {
                "description": "Human-readable explanation of the failure.",
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          }
        },
        "required": [
          "error"
        ],
        "title": "OOMPF Error Envelope",
        "type": "object"
      },
      "ModelMappings": {
        "additionalProperties": false,
        "properties": {
          "models": {
            "items": {
              "$ref": "#/components/schemas/ProfileMappings/$defs/modelDisplay"
            },
            "type": "array"
          },
          "provider": {
            "type": "string"
          }
        },
        "required": [
          "provider",
          "models"
        ],
        "type": "object"
      },
      "ProfileMappings": {
        "$defs": {
          "modelDisplay": {
            "additionalProperties": false,
            "description": "Curated display facts for a model selector. Mirrors ModelDisplay in @oompf/core.",
            "properties": {
              "friendlyName": {
                "description": "Human-friendly model name shown first in the UI.",
                "type": "string"
              },
              "isAlias": {
                "description": "True when the selector is an OMP alias (begins with \"@\").",
                "type": "boolean"
              },
              "providerId": {
                "description": "Owning provider id, or null when unknown/aliased.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "selector": {
                "description": "The exact model selector as written in the artifact.",
                "type": "string"
              },
              "url": {
                "description": "Canonical public URL for the model, or null when not curated (never guessed).",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "selector",
              "friendlyName",
              "providerId",
              "url",
              "isAlias"
            ],
            "type": "object"
          },
          "providerLink": {
            "additionalProperties": false,
            "description": "Curated identity and canonical link for a provider. Mirrors ProviderLink in @oompf/core.",
            "properties": {
              "displayName": {
                "description": "Human-friendly provider name.",
                "type": "string"
              },
              "providerId": {
                "description": "Stable provider id used in selectors and mapping routes.",
                "type": "string"
              },
              "url": {
                "description": "Canonical public URL for the provider, or null when not curated (never guessed).",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "providerId",
              "displayName",
              "url"
            ],
            "type": "object"
          }
        },
        "$id": "https://oompf.run/schemas/profile-mappings.json",
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "Curated provider/model mapping responses. The registry never fabricates unknown links.",
        "oneOf": [
          {
            "additionalProperties": false,
            "description": "Response of GET /api/v1/mappings/providers.",
            "properties": {
              "providers": {
                "items": {
                  "$ref": "#/$defs/providerLink"
                },
                "type": "array"
              }
            },
            "required": [
              "providers"
            ],
            "title": "Provider mappings response",
            "type": "object"
          },
          {
            "additionalProperties": false,
            "description": "Response of GET /api/v1/mappings/models/:provider.",
            "properties": {
              "models": {
                "items": {
                  "$ref": "#/$defs/modelDisplay"
                },
                "type": "array"
              },
              "provider": {
                "description": "The provider id the models belong to.",
                "type": "string"
              }
            },
            "required": [
              "provider",
              "models"
            ],
            "title": "Model mappings response",
            "type": "object"
          }
        ],
        "title": "OOMPF Profile Mappings"
      },
      "ProfileMetadataRecord": {
        "$defs": {
          "profileFacts": {
            "additionalProperties": true,
            "description": "Reliable, source-derived facts about the native OMP artifact. Forward-compatible: unrecognized fields are preserved.",
            "properties": {
              "advisor": {
                "description": "Observed advisor settings, or null when absent.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "aliases": {
                "description": "OMP alias selectors (values beginning with \"@\"), classified out of `models` and `providers`.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "disabledProviders": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "extensions": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "fallbackChains": {
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "models": {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "role": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "models",
                    "role"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "fields": {
                "description": "Recognized scalar identity fields present in the document.",
                "type": "object"
              },
              "hooks": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "modelRoles": {
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "model": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "model",
                    "role"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "models": {
                "description": "Distinct concrete model identifiers (never aliases).",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "prerequisites": {
                "description": "Actionable non-provider requirements only (environment, extension, project-overlay).",
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "kind": {
                      "enum": [
                        "provider",
                        "environment",
                        "project-overlay",
                        "extension"
                      ],
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "reason": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "name",
                    "reason"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "providers": {
                "description": "Providers inferred from `<provider>/<model>` identifiers.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "unknownKeys": {
                "description": "Top-level keys OOMPF does not recognize, preserved for forward compat.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "models",
              "providers",
              "aliases"
            ],
            "type": "object"
          },
          "profileMetadata": {
            "additionalProperties": false,
            "description": "Publisher-curated OOMPF metadata from the optional namespaced `oompf` block. Mirrors ProfileMetadata in @oompf/core.",
            "properties": {
              "kind": {
                "description": "Profile kind. `controlled` is true only when `value` is a standard kind.",
                "oneOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "controlled": {
                        "type": "boolean"
                      },
                      "value": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "controlled",
                      "value"
                    ],
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "links": {
                "description": "Publisher-provided links. Never guessed; only what the author declared.",
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "label",
                    "url"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "summary": {
                "description": "Optional plain-text, length-limited author summary.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "tags": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "summary",
              "kind",
              "tags",
              "links"
            ],
            "type": "object"
          },
          "secretFinding": {
            "additionalProperties": false,
            "description": "A value-free secret finding. Names a path and kind, never the value.",
            "properties": {
              "confidence": {
                "enum": [
                  "high",
                  "low"
                ],
                "type": "string"
              },
              "kind": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              }
            },
            "required": [
              "confidence",
              "kind",
              "path",
              "reason"
            ],
            "type": "object"
          },
          "validationMetadata": {
            "additionalProperties": false,
            "description": "Structural validation results and value-free secret advisories. Never carries a secret value or canonical bytes.",
            "properties": {
              "blocking": {
                "items": {
                  "$ref": "#/$defs/secretFinding"
                },
                "type": "array"
              },
              "byteLength": {
                "description": "UTF-8 byte length of the artifact the metadata was derived from.",
                "type": "integer"
              },
              "errors": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "findings": {
                "items": {
                  "$ref": "#/$defs/secretFinding"
                },
                "type": "array"
              },
              "hash": {
                "description": "SHA-256 of the canonical bytes, for cross-checking sources.",
                "type": "string"
              },
              "structural": {
                "enum": [
                  "valid",
                  "invalid"
                ],
                "type": "string"
              },
              "warnings": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "blocking",
              "byteLength",
              "errors",
              "findings",
              "hash",
              "structural",
              "warnings"
            ],
            "type": "object"
          }
        },
        "$id": "https://oompf.run/schemas/profile-metadata.json",
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "additionalProperties": false,
        "description": "A single indexed OMP profile's metadata-only record. Contains no canonical artifact content.",
        "properties": {
          "contentHash": {
            "description": "Lowercase hex SHA-256 of the canonical source bytes.",
            "type": "string"
          },
          "createdAt": {
            "description": "First-indexed timestamp (ISO 8601).",
            "format": "date-time",
            "type": "string"
          },
          "facts": {
            "$ref": "#/$defs/profileFacts"
          },
          "gistId": {
            "description": "Opaque Gist identifier when the source is a Gist, else null.",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Stable opaque profile identifier (prof_<32 hex>).",
            "pattern": "^prof_[0-9a-f]{32}$",
            "type": "string"
          },
          "metadata": {
            "description": "Publisher-curated OOMPF metadata. May be null for records indexed before the metadata contract.",
            "oneOf": [
              {
                "$ref": "#/$defs/profileMetadata"
              },
              {
                "type": "null"
              }
            ]
          },
          "ompVersion": {
            "description": "OMP version the profile declares it targets, when declared.",
            "type": [
              "string",
              "null"
            ]
          },
          "owner": {
            "description": "Source owner login, or null for anonymous sources.",
            "type": [
              "string",
              "null"
            ]
          },
          "profileName": {
            "description": "Human-facing profile name (validated <name>).",
            "type": "string"
          },
          "revision": {
            "description": "Pinned source revision (git SHA) the metadata was read from.",
            "type": [
              "string",
              "null"
            ]
          },
          "sourceType": {
            "description": "Origin kind, e.g. \"gist\".",
            "type": "string"
          },
          "sourceUrl": {
            "description": "Canonical, normalized source URL; unique across the index.",
            "type": "string"
          },
          "updatedAt": {
            "description": "Last-updated timestamp (ISO 8601); bumped only when metadata changes.",
            "format": "date-time",
            "type": "string"
          },
          "validation": {
            "$ref": "#/$defs/validationMetadata"
          }
        },
        "required": [
          "id",
          "sourceUrl",
          "sourceType",
          "profileName",
          "contentHash",
          "createdAt",
          "updatedAt",
          "facts",
          "validation"
        ],
        "title": "OOMPF Profile Metadata Record",
        "type": "object"
      },
      "ProviderMappings": {
        "additionalProperties": false,
        "properties": {
          "providers": {
            "items": {
              "$ref": "#/components/schemas/ProfileMappings/$defs/providerLink"
            },
            "type": "array"
          }
        },
        "required": [
          "providers"
        ],
        "type": "object"
      },
      "RegisterResponse": {
        "additionalProperties": false,
        "description": "Response of POST /api/v1/profiles.",
        "properties": {
          "id": {
            "pattern": "^prof_[0-9a-f]{32}$",
            "type": "string"
          },
          "source": {
            "description": "Canonical, normalized source URL that was indexed.",
            "type": "string"
          },
          "url": {
            "description": "OOMPF profile page path, /p/<id>.",
            "type": "string"
          },
          "validation": {
            "additionalProperties": false,
            "properties": {
              "errors": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "level": {
                "const": "structural",
                "type": "string"
              },
              "structural": {
                "enum": [
                  "valid",
                  "invalid"
                ],
                "type": "string"
              },
              "warnings": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "level",
              "structural",
              "errors",
              "warnings"
            ],
            "type": "object"
          }
        },
        "required": [
          "id",
          "source",
          "url",
          "validation"
        ],
        "type": "object"
      },
      "SearchResponse": {
        "additionalProperties": false,
        "description": "Response of GET /api/v1/search.",
        "properties": {
          "query": {
            "type": "string"
          },
          "results": {
            "items": {
              "$ref": "#/components/schemas/CompactProfile"
            },
            "type": "array"
          }
        },
        "required": [
          "query",
          "results"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "description": "Canonical machine-readable API for the OOMPF public index of OMP profiles. Responses carry metadata only — never canonical artifact content. Unversioned /api/... routes are compatibility aliases that share these handlers.",
    "title": "OOMPF API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/v1/mappings/models/{provider}": {
      "get": {
        "description": "Curated model patterns, friendly names, and canonical links for a provider. Unknown providers return a not_found error; curated models never carry a guessed URL. Alias: GET /api/mappings/models/{provider}.",
        "operationId": "getModelMappings",
        "parameters": [
          {
            "description": "Provider id, e.g. anthropic.",
            "in": "path",
            "name": "provider",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelMappings"
                }
              }
            },
            "description": "Curated model mappings for the provider."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "The provider id is missing."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "No curated model mappings for the provider."
          }
        },
        "summary": "Curated model mappings for a provider",
        "tags": [
          "mappings"
        ]
      }
    },
    "/api/v1/mappings/providers": {
      "get": {
        "description": "Curated provider identities and canonical links. Providers are never invented and url is null unless a verified destination is curated. Alias: GET /api/mappings/providers.",
        "operationId": "getProviderMappings",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderMappings"
                }
              }
            },
            "description": "The curated provider registry."
          }
        },
        "summary": "Curated provider mappings",
        "tags": [
          "mappings"
        ]
      }
    },
    "/api/v1/profiles": {
      "post": {
        "description": "Fetch, structurally validate, normalize, and index a public GitHub Gist. Persists and returns metadata only. Alias: POST /api/profiles.",
        "operationId": "registerProfile",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "ompVersion": {
                    "description": "OMP version the publisher declares, if any.",
                    "type": "string"
                  },
                  "source": {
                    "description": "A public Gist URL or bare Gist ID.",
                    "type": "string"
                  }
                },
                "required": [
                  "source"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterResponse"
                }
              }
            },
            "description": "The source was indexed (or already indexed)."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "The request body or source is invalid."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "The source Gist was not found."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "The source is ambiguous, or the artifact is structurally invalid or carries blocking secrets."
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "The source could not be reached."
          }
        },
        "summary": "Register a public Gist",
        "tags": [
          "profiles"
        ]
      }
    },
    "/api/v1/profiles/{id}": {
      "get": {
        "description": "Fetch a single profile's metadata, validation, facts, OOMPF metadata, and provenance. Alias: GET /api/profiles/{id}.",
        "operationId": "getProfile",
        "parameters": [
          {
            "description": "Stable opaque profile id (prof_<32 hex>).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^prof_[0-9a-f]{32}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileMetadataRecord"
                }
              }
            },
            "description": "The profile metadata record."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "No indexed profile with that id."
          }
        },
        "summary": "Get profile metadata",
        "tags": [
          "profiles"
        ]
      }
    },
    "/api/v1/search": {
      "get": {
        "description": "Free-text search over the profile index, returning compact metadata-only summaries. Alias: GET /api/search.",
        "operationId": "searchProfiles",
        "parameters": [
          {
            "description": "Free-text query over indexed profile metadata.",
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            },
            "description": "Matching compact profile summaries."
          }
        },
        "summary": "Search profiles",
        "tags": [
          "profiles"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Production",
      "url": "https://oompf.run"
    },
    {
      "description": "Local development",
      "url": "http://localhost:4321"
    }
  ],
  "tags": [
    {
      "description": "Profile registration, metadata, and search.",
      "name": "profiles"
    },
    {
      "description": "Curated provider and model mappings.",
      "name": "mappings"
    }
  ]
}