Skip to content

Conversation

@jenningsanderson
Copy link
Collaborator

@jenningsanderson jenningsanderson commented Aug 13, 2025

Moving to Pydantic!

This PR updates and simplifies the docs to show easier, table-based schema docs.

Enhancements to docs code:

  1. Removes Docusaurus JSON Schema Plugin.
  2. Enables (significantly) faster builds.
  3. Reduction in serving of raw YAML files.

/schema/reference Updates:

Today, everything available under docs.overturemaps.org/schema lives here: https://github.com/OvertureMaps/schema/tree/dev/docs/schema. When docusaurus builds the docs, it fetches the .mdx, schema, and examples from the schema repo. This is a lot of moving parts and kind of ugly.

This PR removes that requirement in favor of simple, machine-readable markdown files that can be self-generated by the schema and used by documentation.

See https://staging.overturemaps.org/docs/pr/222/schema/reference/address/ for an example of how we envision these reference docs rendering.

Next Steps:

Before this is ready to merge, we need to develop the ability for the schema to create self-describing documentation with examples as markdown files, example:

# Place

A Place is a point representation of a real-world facility, service, or amenity.

Place features are compatible with GeoJSON Point features.

## Fields

| Name | Type | Description |
|-----:|:----:|-------------|
| `id` | `string` |  |
| `theme` | `"places"` |  |
| `type` | `"place"` |  |
| `geometry` | `geometry` | Position of the place |
| `names` | `object` (`[Names](../../Names/names)`) (optional) |  |
| `names.primary` | `string` | The most commonly used name. |
| `names.common` | `object` (optional) |  |
...

## Examples

| Column | Value |
|-------:|-------|
| `geometry` | `POINT (-151.7990018 -79.5664328)` |
| `categories.alternate` | `null` |
| `categories.primary` | `media_news_website` |
| `confidence` | `0.8015267175572519` |
| `websites` | `[https://www.primenewsmonde.bj/]` |

The full schema should be a series of markdown files nested by theme/type that have relative links. We can adjust the SmartTable component as necessary to make the links work — but the markdown should be a nice, standalone set of files.

If the examples that were embedded were actually derived from the examples in the schema repository after being validated by the schema itself, that would be best case scenario.

Once this ability exists, we can update this repository to fetch these markdown files (or checkout schema and build the markdown as part of the publish). The idea is these files can be dropped directly into docs/schema to power this part of the documentation.

Docs Preview

Example:
image

@jenningsanderson jenningsanderson force-pushed the injectable-schema-refs branch 3 times, most recently from b6bf09d to fa2e953 Compare August 16, 2025 00:09
@danabauer danabauer self-assigned this Sep 17, 2025
@jenningsanderson jenningsanderson added documentation Improvements or additions to documentation enhancement New feature or request labels Feb 7, 2026
@jenningsanderson jenningsanderson changed the base branch from main to gif-to-mp4-conversion February 9, 2026 19:49
@jenningsanderson jenningsanderson force-pushed the injectable-schema-refs branch 2 times, most recently from ad1679b to d936cb3 Compare February 9, 2026 19:59
@jenningsanderson jenningsanderson changed the base branch from gif-to-mp4-conversion to main February 9, 2026 20:19
This change restructures the docs build to remove the dependency on the schema repository, enabling faster builds and simpler deployment.

Key changes:
- Add injectable schema references for dynamic content
- Reorganize example files and schema definitions
- Optimize image assets (convert large GIFs to MP4s, compress PNGs)
- Add staging deployment workflow
- Update linting and formatting configurations
- Fix package-lock.json for cross-platform compatibility
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants