Format & Governance¶
- JSON, Schema.org
Dataset+DefinedTerm/Product, served at stable URLs. - Build-time static generation (MkDocs); no runtime database in Phase 1.
- Never expose sensitive or proprietary data.
- Data changes require source traceability (
termCode/ reference fields).
License & versioning¶
- Every dataset is licensed CC BY-SA 4.0 (share-alike, attribution required) and carries a
license,version,dateModified, andchangelogfield. - Bump the minor
versionon any entity or structure change; record the change inchangelog.
Evidence level¶
Every source object carries an evidenceLevel field, assigned by source nature:
| Tier | Label | Source nature |
|---|---|---|
| Tier 1 | Scientific / Government | government checklists and regulatory lists (e.g. CITES) |
| Tier 2 | Academic / Museum / Institutional | botanical and taxonomic institutions (e.g. GBIF, Flora of China / eFloras) |
| Tier 3 | Historical primary source | classical Chinese texts (e.g. 本草綱目 / 香乘 on Wikisource) |
| Tier 4 | Industry / Trade terminology | trade and industry sources |
| Tier 5 | Traditional knowledge | traditional-knowledge sources |
| Tier 6 | Editorial synthesis | this site's own editorial pages |
Main-site connection¶
- Every ingredient entity carries a canonical
urlpointing at its human-readable page on the main site (https://incenseherbs.com/ingredients/<termCode>/). - The main site links back through
sameAsto the data entity anchor (https://data.incenseherbs.com/ingredients/#<termCode>). - The data site holds structured facts, relationships and evidence; the main site holds the detailed explanation. No full-article duplication between the two.
Source status¶
- Every source is a citation object
{ type, title, url, accessed, evidenceLevel }. - Source URLs must be on the allow-list (efloras.org / gbif.org / wikisource.org / checklist.cites.org / data.incenseherbs.com / incenseherbs.com / schema.org); the
licensefield is the only exception (creativecommons.org).
CSV distribution¶
- Every dataset also ships as a flat CSV distribution package, generated from the JSON source by
scripts/export_csv.py— no new fact is introduced. - CSV columns flatten the
mainEntityarray with Chinese and English names side by side (name_zh/name_en) plus each dataset'sadditionalPropertyvalues as columns. - Files are UTF-8 with a BOM so Excel opens them directly;
relationships.csvis an edge list (one row per relation). - CSVs are regenerated on every
mkdocs buildintosite/downloads/*.csv(served fromdata.incenseherbs.com/downloads/).
Entity pages & retrieval index¶
docs/entities/ is auto-generated by scripts/generate-entity-pages.py from
datasets/*.json (single source of truth). Do not edit by hand.
- One page per entity termCode:
/entities/<termCode>/ - Entity datasets: ingredients, aroma, materials, techniques, forms, comparisons (205 pages; shared termCodes merge into a single page)
terminologykeeps its anchor index on the terminology page- Each page: entity-level JSON-LD (DefinedTerm) → Claim & Evidence → Attributes → Relationships (resolvable links only) → main-site link
- Retrieval index:
entities/index.json(machine-readable ItemList) check-consistency.pyverifies: no orphan pages, no missing pages, no broken /entities/ links, index count == page count
Deprecation¶
- To retire an entity without deleting it, set
"deprecated": trueon the entity. - To replace an entity, point the old one at its successor with
"supersededBy": "<termCode>". - Deprecated entities remain resolvable at their stable
termCode; they are excluded from new relationships.