{
  "openapi": "3.1.0",
  "info": {
    "title": "Metacrafter Registry API",
    "version": "1.3.0.dev0",
    "description": "Static, read-only JSON files describing semantic data types. No authentication, no query parameters.",
    "license": {
      "name": "Apache-2.0",
      "identifier": "Apache-2.0"
    }
  },
  "servers": [
    {
      "url": "http://registry.apicrafter.io"
    }
  ],
  "paths": {
    "/api/v1/index.json": {
      "get": {
        "operationId": "getManifest",
        "summary": "Registry manifest: version, counts, file hashes, URL template",
        "responses": {
          "200": {
            "description": "Manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Manifest"
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/datatypes.json": {
      "get": {
        "operationId": "listDatatypes",
        "summary": "All datatypes and patterns",
        "responses": {
          "200": {
            "description": "Array of records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Datatype"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/datatypes/{id}.json": {
      "get": {
        "operationId": "getDatatype",
        "summary": "One datatype or pattern by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Datatype or pattern id, e.g. email",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9_]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Datatype"
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/tools.json": {
      "get": {
        "operationId": "listTools",
        "summary": "All tools",
        "responses": {
          "200": {
            "description": "Array of tools",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Tool"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/tools/{id}.json": {
      "get": {
        "operationId": "getTool",
        "summary": "One tool by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tool id, e.g. presidio",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9_]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tool"
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/categories.json": {
      "get": {
        "operationId": "listCategories",
        "summary": "Categories (contexts of use) with record counts",
        "responses": {
          "200": {
            "description": "Array of references",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Reference"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/countries.json": {
      "get": {
        "operationId": "listCountries",
        "summary": "Countries and regions with record counts",
        "responses": {
          "200": {
            "description": "Array of references",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Reference"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/languages.json": {
      "get": {
        "operationId": "listLanguages",
        "summary": "Languages with record counts",
        "responses": {
          "200": {
            "description": "Array of references",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Reference"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/aliases.json": {
      "get": {
        "operationId": "listAliases",
        "summary": "Retired ids and the canonical id each one resolves to",
        "responses": {
          "200": {
            "description": "Object: alias -> canonical id",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/api/v1/coverage.json": {
      "get": {
        "operationId": "getCoverage",
        "summary": "metacrafter-rules coverage: datatypes without rules, orphan rule keys",
        "responses": {
          "200": {
            "description": "Coverage report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/registry.json": {
      "get": {
        "operationId": "getLegacyRegistry",
        "summary": "Legacy: all records keyed by id (used by metacrafter RegistryClient)",
        "responses": {
          "200": {
            "description": "Object keyed by id",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "$ref": "#/components/schemas/LegacyRecord"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    },
    "/datatype/{id}.json": {
      "get": {
        "operationId": "getLegacyDatatype",
        "summary": "Legacy: one record in the release 1.02 shape",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Datatype or pattern id",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9_]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Legacy record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyRecord"
                }
              }
            }
          },
          "404": {
            "description": "No such record"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Example": {
        "type": "object",
        "required": [
          "value",
          "valid"
        ],
        "properties": {
          "value": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "valid": {
            "type": "boolean",
            "description": "false marks a negative example that must not match"
          }
        }
      },
      "Link": {
        "type": "object",
        "required": [
          "type",
          "url"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "wikipedia, wikidata, schema.org, doc, dublincore, bioschemas, datadrivendiscovery or other"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Translation": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "doc": {
            "type": "string"
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "path",
          "url",
          "edit_url"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "YAML source file in the repository"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "edit_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Urls": {
        "type": "object",
        "required": [
          "html",
          "json"
        ],
        "properties": {
          "html": {
            "type": "string",
            "format": "uri"
          },
          "json": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Datatype": {
        "type": "object",
        "description": "A semantic datatype, or a pattern (one representation of a datatype). Optional fields are omitted when empty.",
        "required": [
          "id",
          "kind",
          "status",
          "name",
          "doc",
          "is_pii",
          "quality",
          "source",
          "urls"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "datatype",
              "pattern"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "stable",
              "deprecated"
            ],
            "description": "draft: not reviewed yet, do not treat as authoritative"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Former ids that resolve to this record"
          },
          "replaced_by": {
            "type": "string"
          },
          "checksum": {
            "type": "string",
            "description": "Check-digit algorithm name"
          },
          "quality": {
            "type": "object",
            "required": [
              "score",
              "missing"
            ],
            "properties": {
              "score": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "missing": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "name": {
            "type": "string"
          },
          "doc": {
            "type": "string"
          },
          "semantic_type": {
            "type": "string",
            "description": "For patterns: id of the datatype it represents"
          },
          "parent": {
            "type": "string",
            "description": "id of the parent datatype"
          },
          "children": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "patterns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "is_pii": {
            "type": "boolean"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISO 3166-1 alpha-2 codes (EU = region)"
          },
          "langs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISO 639-1 codes; 'common' = any language"
          },
          "classification": {
            "type": "string"
          },
          "regexp": {
            "type": "string",
            "description": "Python re syntax"
          },
          "examples": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Example"
            }
          },
          "mappings": {
            "type": "object",
            "description": "Identifiers of the same concept in other vocabularies",
            "properties": {
              "wikidata": {
                "type": "string",
                "pattern": "^[PQ][0-9]+$"
              },
              "fibo": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ],
                "description": "FIBO class IRI without the https://spec.edmcouncil.org/fibo/ontology/ prefix"
              }
            },
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            }
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            }
          },
          "translations": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/Translation"
            },
            "description": "Keyed by language code"
          },
          "detected_by": {
            "type": "object",
            "properties": {
              "tools": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "metacrafter_rules": {
                "type": "array",
                "description": "Rules of the pinned metacrafter-rules release",
                "items": {
                  "type": "object",
                  "required": [
                    "rule",
                    "type",
                    "match",
                    "file"
                  ],
                  "properties": {
                    "rule": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "description": "field or data"
                    },
                    "match": {
                      "type": "string"
                    },
                    "file": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string",
                      "description": "when the rule uses an alias"
                    }
                  }
                }
              }
            }
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "urls": {
            "$ref": "#/components/schemas/Urls"
          }
        }
      },
      "Tool": {
        "type": "object",
        "required": [
          "id",
          "name",
          "category",
          "doc",
          "supported_types",
          "source",
          "urls"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "doc": {
            "type": "string"
          },
          "website": {
            "type": "string",
            "format": "uri"
          },
          "supported_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "urls": {
            "$ref": "#/components/schemas/Urls"
          }
        }
      },
      "Reference": {
        "type": "object",
        "required": [
          "id",
          "name",
          "count"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "description": "Datatypes and patterns that use it"
          },
          "kind": {
            "type": "string",
            "description": "country or region; language or special ('common' = any language)"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "FileInfo": {
        "type": "object",
        "required": [
          "path",
          "bytes",
          "sha256"
        ],
        "properties": {
          "path": {
            "type": "string"
          },
          "bytes": {
            "type": "integer"
          },
          "sha256": {
            "type": "string"
          }
        }
      },
      "Manifest": {
        "type": "object",
        "required": [
          "name",
          "version",
          "datatype_url_template",
          "counts",
          "files"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "git_sha": {
            "type": [
              "string",
              "null"
            ]
          },
          "generated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "license": {
            "type": "string"
          },
          "base_url": {
            "type": "string",
            "format": "uri"
          },
          "datatype_url_template": {
            "type": "string"
          },
          "counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "files": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/FileInfo"
            }
          }
        }
      },
      "LegacyRecord": {
        "type": "object",
        "description": "Release 1.02 shape: categories, country and langs are {id, name} objects; patterns are embedded objects.",
        "required": [
          "id",
          "name",
          "doc",
          "type",
          "is_pii"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "doc": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "datatype",
              "pattern"
            ]
          },
          "is_pii": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      }
    }
  }
}