schemaorg-pydantic 0.1.0__tar.gz

schemaorg_pydantic-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - run: uv python install ${{ matrix.python-version }}
+
+      - run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Test
+        run: uv run pytest
+
+  minimum:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Test with the oldest pydantic and Python that are supported
+        run: uv run --python 3.10 --with "pydantic==2.7.0" pytest
+
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: uv sync
+
+      - name: Type check the package and how a user types against it
+        run: uv run mypy src tests/typing_check.py
+
+  generated:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: uv sync
+
+      - name: Regenerate from the pinned schema.org release
+        run: uv run python -m scripts.update
+
+      - name: The committed models are what the pinned release generates
+        run: test -z "$(git status --porcelain)"

schemaorg_pydantic-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: uv build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

schemaorg_pydantic-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Create Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to release (e.g. v0.1.0)"
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get schema.org release
+        id: schema
+        run: echo "version=$(jq -r .release scripts/pin.json)" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG=${{ github.ref_name != 'master' && github.ref_name || inputs.tag }}
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --draft \
+            --notes "Generated from [schema.org ${{ steps.schema.outputs.version }}](https://schema.org/docs/releases.html)."

schemaorg_pydantic-0.1.0/.github/workflows/update-schema.yml

@@ -0,0 +1,53 @@
+name: Update schema.org
+
+on:
+  schedule:
+    - cron: "0 9 * * 1" # Every Monday at 9:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.RELEASE_TOKEN_SCHEMAORG_PYDANTIC }}
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: uv sync
+
+      - name: Generate from the newest release
+        id: update
+        run: |
+          set +e
+          uv run python -m scripts.update --latest
+          status=$?
+          set -e
+          if [ "$status" -ne 0 ] && [ "$status" -ne 10 ]; then exit "$status"; fi
+          echo "changed=$([ "$status" -eq 10 ] && echo true || echo false)" >> $GITHUB_OUTPUT
+
+      - name: Test
+        if: steps.update.outputs.changed == 'true'
+        run: uv run pytest
+
+      - name: Bump version
+        id: version
+        if: steps.update.outputs.changed == 'true'
+        run: |
+          uv version --bump patch
+          echo "new_version=$(uv version --short)" >> $GITHUB_OUTPUT
+
+      - name: Commit and tag
+        if: steps.update.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A src/schemaorg_pydantic scripts/pin.json pyproject.toml uv.lock
+          git commit -m "chore: sync with schema.org $(jq -r .release scripts/pin.json)"
+          git tag "v${{ steps.version.outputs.new_version }}"
+          git push && git push --tags

schemaorg_pydantic-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.cache/

schemaorg_pydantic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey Jurjens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

schemaorg_pydantic-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: schemaorg-pydantic
+Version: 0.1.0
+Summary: Typed schema.org models for pydantic, generated from the schema.org vocabulary, with a JSON-LD writer
+Project-URL: Repository, https://github.com/joeyjurjens/schemaorg-pydantic
+Author-email: Joey Jurjens <joeyjurjens@gmail.com>
+License-File: LICENSE
+Keywords: json-ld,pydantic,schema.org,seo,structured-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# schemaorg-pydantic
+
+[schema.org](https://schema.org) types as strict [pydantic](https://docs.pydantic.dev) models, generated from the schema.org vocabulary, with a JSON-LD writer. Python 3.10 and newer, and pydantic 2.7 or newer.
+
+## Install
+
+```bash
+pip install schemaorg-pydantic
+```
+
+## Use
+
+```python
+from schemaorg_pydantic import Brand, Graph, ItemAvailability, Offer, Organization, Product
+
+shop = Organization(id="https://example.com/#organization", name="Northwind")
+product = Product(
+    id="https://example.com/p/blue-bag/#product",
+    name="Blue bag",
+    brand=Brand(name="Northwind"),
+    manufacturer=shop,
+    offers=Offer(price=79, price_currency="EUR", availability=ItemAvailability.IN_STOCK),
+)
+
+product.to_jsonld()  # a dict, with @context
+product.to_script()  # <script type="application/ld+json">...</script>, safe to put in HTML
+Graph(shop, product).script()  # several nodes as one @graph
+```
+
+`to_jsonld()` and `to_script()` are short for `JsonLd` in `schemaorg_pydantic.jsonld` (also importable from `schemaorg_pydantic`), the one place that writes a node as JSON-LD. The models themselves are plain pydantic models, so `model_dump()` works as for any other, and another format would be another module. `Graph` writes nodes that are used more than once as a reference.
+
+## What is checked
+
+Fields are snake_case (`price_currency`) and written to JSON-LD under the schema.org name (`priceCurrency`). Both spellings are accepted when you build a model, so a property can be copied from schema.org as it is, but a type checker only knows the Python names. Enumeration members are upper case (`ItemAvailability.IN_STOCK`), and a module is named like its type in snake_case (`product_group.py`).
+
+A date is a `date` or `datetime`, or an ISO 8601 string (`"2026-12-31"`, `"2026-11-12T10:00:00+01:00"`). A wrong type, an unknown property, a relative URL, a date that is not ISO 8601, a value of the wrong class and an availability that is not a schema.org value all raise a `ValidationError` when the model is built, and again when a value is assigned later. Enumerations are enums whose value is the schema.org address, so `ItemAvailability.IN_STOCK` is written as the text `https://schema.org/InStock`, the way Google's documentation writes it. A strict JSON-LD processor reads that as a text value and not as an IRI, because the schema.org context does not say otherwise.
+
+This package writes JSON-LD and does not read it: a nested value must be a model, not a dict, so `Product.model_validate({...})` only works for flat data. To read JSON-LD use [TRLD](https://pypi.org/project/trld/), [PyLD](https://pypi.org/project/PyLD/) or RDFLib.
+
+In a `Graph`, a node with an `@id` that is used more than once is written once and referenced everywhere else. Two nodes with one `@id` that disagree raise `GraphConflict`; two that complement each other are merged. A property whose name is a Python keyword gets a trailing underscore (`yield_`) and is written under its own name.
+
+For other formats, hand the JSON-LD to an RDF library: [RDFLib](https://rdflib.readthedocs.io) (`Graph().parse(data=..., format="json-ld")`, then `serialize(format="turtle")`) or [TRLD](https://pypi.org/project/trld/). The tests read the output with TRLD to check that it is valid JSON-LD 1.1 and that every reference points at a node that exists.
+
+Every type and every property is tested against the pinned schema.org release: each type exists and inherits from exactly its ancestors, each property is a field of the types it belongs to and takes every kind of value schema.org lists for it, each enumeration has its members. The release is downloaded once into `.cache`.
+
+This package does not know what Google requires for a rich result. schema.org does not carry that, so it is data for whoever consumes the models.
+
+## The models are generated
+
+`src/schemaorg_pydantic/models/` and `__init__.py` are generated from a pinned schema.org release (`scripts/pin.json`) and holds the whole vocabulary: 825 types and 80 enumerations as of 30.1, including the pending and the health and life sciences parts, one module for each, in one folder. Types that schema.org has superseded are left out.
+
+A type is imported when it is first used, so `import schemaorg_pydantic` loads none of them (about 31 MB with pydantic, against 19 MB for pydantic alone) and a product with an offer and a brand loads ten small modules. A reference from one type to another is checked by name, so it does not pull the other type in. To regenerate:
+
+```bash
+uv run python -m scripts.update
+```
+
+`scripts/range_overrides.json` holds the few places where Google accepts more than schema.org lists, each with the page that says so.
+
+A weekly workflow takes the newest schema.org release, regenerates the models, runs the tests, bumps the patch version and tags it. CI checks that the committed models are what the pinned release generates.
+
+## Licence
+
+The code is MIT. The descriptions in the docstrings of the models are taken from schema.org and are available under the [Creative Commons Attribution-ShareAlike License (CC BY-SA 3.0)](https://schema.org/docs/terms.html).

schemaorg_pydantic-0.1.0/README.md

@@ -0,0 +1,64 @@
+# schemaorg-pydantic
+
+[schema.org](https://schema.org) types as strict [pydantic](https://docs.pydantic.dev) models, generated from the schema.org vocabulary, with a JSON-LD writer. Python 3.10 and newer, and pydantic 2.7 or newer.
+
+## Install
+
+```bash
+pip install schemaorg-pydantic
+```
+
+## Use
+
+```python
+from schemaorg_pydantic import Brand, Graph, ItemAvailability, Offer, Organization, Product
+
+shop = Organization(id="https://example.com/#organization", name="Northwind")
+product = Product(
+    id="https://example.com/p/blue-bag/#product",
+    name="Blue bag",
+    brand=Brand(name="Northwind"),
+    manufacturer=shop,
+    offers=Offer(price=79, price_currency="EUR", availability=ItemAvailability.IN_STOCK),
+)
+
+product.to_jsonld()  # a dict, with @context
+product.to_script()  # <script type="application/ld+json">...</script>, safe to put in HTML
+Graph(shop, product).script()  # several nodes as one @graph
+```
+
+`to_jsonld()` and `to_script()` are short for `JsonLd` in `schemaorg_pydantic.jsonld` (also importable from `schemaorg_pydantic`), the one place that writes a node as JSON-LD. The models themselves are plain pydantic models, so `model_dump()` works as for any other, and another format would be another module. `Graph` writes nodes that are used more than once as a reference.
+
+## What is checked
+
+Fields are snake_case (`price_currency`) and written to JSON-LD under the schema.org name (`priceCurrency`). Both spellings are accepted when you build a model, so a property can be copied from schema.org as it is, but a type checker only knows the Python names. Enumeration members are upper case (`ItemAvailability.IN_STOCK`), and a module is named like its type in snake_case (`product_group.py`).
+
+A date is a `date` or `datetime`, or an ISO 8601 string (`"2026-12-31"`, `"2026-11-12T10:00:00+01:00"`). A wrong type, an unknown property, a relative URL, a date that is not ISO 8601, a value of the wrong class and an availability that is not a schema.org value all raise a `ValidationError` when the model is built, and again when a value is assigned later. Enumerations are enums whose value is the schema.org address, so `ItemAvailability.IN_STOCK` is written as the text `https://schema.org/InStock`, the way Google's documentation writes it. A strict JSON-LD processor reads that as a text value and not as an IRI, because the schema.org context does not say otherwise.
+
+This package writes JSON-LD and does not read it: a nested value must be a model, not a dict, so `Product.model_validate({...})` only works for flat data. To read JSON-LD use [TRLD](https://pypi.org/project/trld/), [PyLD](https://pypi.org/project/PyLD/) or RDFLib.
+
+In a `Graph`, a node with an `@id` that is used more than once is written once and referenced everywhere else. Two nodes with one `@id` that disagree raise `GraphConflict`; two that complement each other are merged. A property whose name is a Python keyword gets a trailing underscore (`yield_`) and is written under its own name.
+
+For other formats, hand the JSON-LD to an RDF library: [RDFLib](https://rdflib.readthedocs.io) (`Graph().parse(data=..., format="json-ld")`, then `serialize(format="turtle")`) or [TRLD](https://pypi.org/project/trld/). The tests read the output with TRLD to check that it is valid JSON-LD 1.1 and that every reference points at a node that exists.
+
+Every type and every property is tested against the pinned schema.org release: each type exists and inherits from exactly its ancestors, each property is a field of the types it belongs to and takes every kind of value schema.org lists for it, each enumeration has its members. The release is downloaded once into `.cache`.
+
+This package does not know what Google requires for a rich result. schema.org does not carry that, so it is data for whoever consumes the models.
+
+## The models are generated
+
+`src/schemaorg_pydantic/models/` and `__init__.py` are generated from a pinned schema.org release (`scripts/pin.json`) and holds the whole vocabulary: 825 types and 80 enumerations as of 30.1, including the pending and the health and life sciences parts, one module for each, in one folder. Types that schema.org has superseded are left out.
+
+A type is imported when it is first used, so `import schemaorg_pydantic` loads none of them (about 31 MB with pydantic, against 19 MB for pydantic alone) and a product with an offer and a brand loads ten small modules. A reference from one type to another is checked by name, so it does not pull the other type in. To regenerate:
+
+```bash
+uv run python -m scripts.update
+```
+
+`scripts/range_overrides.json` holds the few places where Google accepts more than schema.org lists, each with the page that says so.
+
+A weekly workflow takes the newest schema.org release, regenerates the models, runs the tests, bumps the patch version and tags it. CI checks that the committed models are what the pinned release generates.
+
+## Licence
+
+The code is MIT. The descriptions in the docstrings of the models are taken from schema.org and are available under the [Creative Commons Attribution-ShareAlike License (CC BY-SA 3.0)](https://schema.org/docs/terms.html).

schemaorg_pydantic-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "schemaorg-pydantic"
+version = "0.1.0"
+description = "Typed schema.org models for pydantic, generated from the schema.org vocabulary, with a JSON-LD writer"
+readme = "README.md"
+authors = [
+    { name = "Joey Jurjens", email = "joeyjurjens@gmail.com" }
+]
+requires-python = ">=3.10"
+license-files = ["LICENSE"]
+dependencies = [
+    "pydantic>=2.7",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Typing :: Typed",
+]
+keywords = ["schema.org", "pydantic", "json-ld", "structured-data", "seo"]
+
+[project.urls]
+Repository = "https://github.com/joeyjurjens/schemaorg-pydantic"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/schemaorg_pydantic"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.1",
+    "pytest>=8",
+    "ruff>=0.15.18",
+    "trld>=0.3.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+markers = ["vocabulary: checks the generated models against the pinned schema.org release, which is downloaded once into .cache"]
+
+[tool.ruff]
+line-length = 100
+extend-exclude = ["src/schemaorg_pydantic/models", "src/schemaorg_pydantic/__init__.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]