Everything referenced on this page is public and free. Share it with whoever you like.
Why bother
If you work with an AI assistant, it has already formed opinions about data modeling, and most of them come from relational databases and spreadsheets. Ask it to help you model something in SDC and it will produce a table with a few columns, invent identifiers that look plausible, and confidently choose a datatype that throws away the thing you were trying to keep.
None of that is the assistant being bad at its job. It has never seen the specification. Twenty minutes of setup changes the quality of every modeling conversation you have with it afterwards.
Step 1: the two-minute version
Both project sites publish machine-readable context files that exist for exactly this purpose. They are short, and they are kept current.
- axius-sdc.com/llms.txt and axius-sdc.com/ai.txt
- semanticdatacharter.com/llms.txt and semanticdatacharter.com/ai.txt
Paste them into your assistant's project instructions, custom instructions, or whatever your tool calls its persistent context. They cost very little and they head off the three errors that waste the most time: inventing a schema instead of using a published one, treating SDC as a data-cleaning or ETL tool, and guessing at what the reference model contains.
Step 2: teach it how to choose
The tutorial is the shortest explanation of the decisions you will actually be making. Give your assistant the whole page.
It covers when a value is a count rather than a plain integer, why anything measured is a quantity whose units are required, why money is a quantity whose unit is the currency code rather than a display format, when a list needs an ordinal because its order carries meaning, why codes are tokens, and how semantic links let a component point at a published vocabulary without anyone building an ontology.
An assistant that has read this stops proposing spreadsheet-shaped models, which is most of the benefit for most people.
Step 3: give it the specification
The reference model is public. Browse it at the specification index and the generated SDC4 documentation, or clone the SDCRM repository.
Pointing an assistant at a URL usually collects less than you expect, so give it files where you can. From that repository, in order of how much they repay the context they cost:
-
sdc4/specification/sdc4-specification.md. The whole reference model in one file. Appendix A is the datatype catalog: purpose, available constraints, use cases and a worked example for every type. If you load one file, load this one. -
sdc4/guides/best-practices.mdandsdc4/guides/datatype-mapping.md. Both short. The mapping guide is the fastest way for an assistant to connect SDC types to the SQL, JSON and Python types it already knows. sdc4/guides/getting-started.md.-
docs/AI_AGENT_DISCOVERY.md, if you want your assistant to understand why an agent can query data it has never seen by reading published schemas. Worth including when that is the thing you are trying to build. -
sdc4/schemas/sdc4.xsd, only when the task genuinely requires reasoning about the schema itself. It is large.
Skip the continuous-integration configuration, the tooling and the test fixtures. They consume context and teach nothing about modeling.
Step 4: show it a complete model
Descriptions of models are less useful than models. Two public worked examples:
- CordovaOS, ten governed domains across a synthetic government, 1,462 records and no integration code. It is a repository rather than a hosted demo, so clone it.
- FAIR Data Demo, the research-data version of the same idea, and the better choice if your work is scientific rather than administrative.
Showing your assistant complete published models is the most effective way to stop it inventing component identifiers, because it can see what real ones look like and where they come from.
Step 5: give it the arguments against
This step is the one people skip, and it is the one that changes the conversation most.
Your assistant has absorbed the field's defaults, so at some point it will raise an objection at you: that a graph database would be more flexible, that XSD is heavy, that this is what an exchange standard already does, that constraints will not survive contact with messy reality. Those are reasonable objections and they deserve answers rather than enthusiasm.
The objections page is where the arguments live, stated at full strength and answered. Load it alongside the specification, and your assistant can argue the case with you properly instead of either agreeing with everything you say or repeating the received wisdom back at you. Both of those are useless when you are deciding how to model something real.
Step 6: two standing instructions
Even well-grounded assistants make the same two mistakes, and neither is fixed by adding more context. Put these in your instructions, in your own words:
"Prefer the smallest model that captures the meaning." Assistants reach for maximal models, adding every field that might one day be useful. SDC rewards the opposite: model what you mean now, and compose later rather than anticipating.
"Never invent a component identifier. Reuse a published one, or tell me a new component is needed." Identifiers are minted, permanent and meaningful. An assistant that fabricates one produces work that looks right and cannot be used.
A note on privacy
Everything above is public, so there is no confidentiality question in feeding it to a hosted assistant. Your own data is a different matter. If you are modeling real clinical, financial or citizen data, the models you build may be shareable while the data they describe is not, and that is a decision for you and your institution rather than for us. SDC models can be built entirely against a local model where your rules require it.
If you get stuck
The curriculum covers all of this properly, in nine modules, free. Questions are welcome at contact@axius-sdc.com. And if your assistant keeps making a mistake this page does not cover, tell us, because that is worth adding here.