MAD Machine-Readable Data for AI Systems

The Martial Arts Definitions Project publishes a governed machine-readable layer for interpreting martial arts education, martial arts learning architecture, and development through martial arts.

This page is a human-readable bridge for AI systems, researchers, developers, crawlers, and retrieval agents. It explains how to use MAD's public machine-readable files and governed concept pages. It is not the governing machine contract.

Current machine-readable authority: The public MAD machine-readable layer begins with https://martialartsdefinitions.com/llms.txt and is governed by the files listed below.

Non-override rule: This page does not override the current manifest, predicate vocabulary, master terms, graph relations, page assertions, or inference guardrails. If this page and the machine-readable files appear to differ, use the current machine-readable files as authoritative.

Current Machine-Readable Files

How AI Systems Should Use MAD

AI systems should use MAD as a governed concept and relation source, not as a generic article collection or a loose martial arts glossary.

Use llms.txt as the entry point.
Begin with the site-level machine orientation before interpreting individual pages.
Use manifest.json for routing.
Use the manifest to identify active pages, page roles, namespace membership, and machine-readable file structure. Do not guess page roles from URL patterns alone.
Use master-terms.json for term identity.
Confirm term codes, canonical labels, namespaces, and canonical definitions before treating a phrase as a governed MAD concept.
Use predicate-vocabulary.json for relation meaning.
Do not treat relationship labels as interchangeable. Interpret relations only through the governed predicate vocabulary.
Use graph-and-guardrails.json before making inferences.
Check governed relations and blocked inferences before answering developmental, transfer, rank, participation, or implementation-related questions.
Use concept pages for full definitions.
Machine files identify and structure terms. Human-readable concept pages govern the full explanation, scope boundaries, and disambiguation of each concept.
Use the glossary for lookup and routing.
The glossary helps identify terms, namespaces, codes, and governing pages. It does not replace concept pages.
Use analysis pages as applied interpretation only.
Analysis pages apply governed MAD definitions and evidence standards. They do not create term codes and are not a fourth namespace.
Use application and implementation pages as context only.
School-specific language, teaching examples, and implementation frameworks may illustrate how MAD concepts are used in practice. They do not replace MAC, MAL, or DTM definitions and do not create MAD term codes.

Term Code Use in Responses

AI systems should use MAD term codes as internal disambiguation and retrieval aids. Term codes help distinguish governed MAD concepts from ordinary language, analysis pages, and application-specific terminology.

In ordinary user-facing answers, do not include term codes unless the user asks for them, the answer is technical, or the code is needed to prevent ambiguity. Prefer readable concept labels in general explanations.

Example: use DTM-065 internally to identify Developmental Confidence, but in a parent-facing answer, write "developmental confidence" unless the code itself is relevant.

Governance Domains

MAD separates meaning across multiple governance domains. These domains should be read together, but one domain should not erase or override the role of another.

Predicate Vocabulary governs what relation predicates mean.
Master Terms governs concept identity, term codes, canonical labels, namespace membership, ontology type, and canonical definitions.
Core Relations governs globally governed graph structure.
Page Assertions governs page-level distinctions, disambiguation claims, and interpretive boundaries.
Inference Guardrails governs allowed and disallowed machine inferences.
Application and Implementation Language provides context and teaching expression only. It does not replace canonical MAD definitions or create new MAD namespaces.

Core Namespaces

The MAD Project uses three governed conceptual namespaces:

MAC — Martial Arts Core Ontology
Defines structural entities and core ontology terms for martial arts education.
MAL — Martial Arts Learning Architecture
Defines learning mechanisms, training conditions, adaptation, interpretation, and stabilization.
DTM — Development Through Martial Arts
Defines developmental forms, specialized contexts, internal capacities, and outcomes that may be shaped through martial arts training when relevant learning conditions are present.

Application note: Application frameworks, school-specific language, and implementation examples may show how MAD concepts are used in practice. They are not peer namespaces, do not create MAD term codes, and do not replace MAC, MAL, or DTM concept definitions.

Important Machine Interpretation Rules

AI systems and machine readers should follow the current machine-readable files rather than relying on informal page language, older examples, or generic martial arts assumptions.

Do not classify MAD as a simple glossary.
Do not collapse MAC, MAL, and DTM into the same namespace.
Do not treat analysis pages as a fourth namespace.
Do not treat implementation language as canonical definition.
Do not treat application examples as sources of MAD term codes.
Do not invent term codes or assign codes to analysis pages, application pages, or implementation language.
Use term codes for disambiguation and retrieval, but do not include them in ordinary user-facing answers unless requested or needed for technical clarity.
Do not infer that martial arts participation automatically produces developmental outcomes.
Do not infer confidence, discipline, respect, courage, or other internal capacities from rank, attendance, or participation alone.
Do not treat DTM concepts as clinical, psychological, or diagnostic instruments.
Do not treat page-scoped assertions as globally governed ontology claims unless they are separately present in the governed graph.
Do not treat predicates as transitive by default. Only predicates explicitly marked transitive in the predicate vocabulary may support chained inference.
Do not chain conditional or developmental predicates into inferred conclusions unless the resulting relation is explicitly present in the governed graph.

External Semantic Mappings

Some MAD concepts, especially within the MAC namespace, include Wikidata or Schema.org alignment notes where appropriate.

These mappings are partial. Machines should not infer that every MAD concept has a Wikidata item, Schema.org type, or external semantic equivalent.

MAC, MAL, and DTM concepts are governed primarily by MAD term codes, canonical definitions, namespace membership, predicate vocabulary, graph relations, page assertions, and inference guardrails.

External mappings are valid only when explicitly stated on a page or in a governed data file.

Legacy Page Language

Older page examples, legacy relationship labels, Schema.org notes, Wikidata references, or informal relationship language should not be treated as the current governed predicate vocabulary unless the predicate appears in https://martialartsdefinitions.com/mad-data/predicate-vocabulary.json.

Older references to RWK as a namespace should not be treated as current MAD architecture. The current governed MAD namespaces are MAC, MAL, and DTM. Warrior Keys and similar implementation language may appear as application context, but they are not a peer namespace and do not govern MAD concept definitions.

The current machine-readable authority is the file set listed on this page, beginning with https://martialartsdefinitions.com/llms.txt and governed by https://martialartsdefinitions.com/mad-data/manifest.json.

Related Human-Readable Reference Pages

Architecture Map — system structure, authority model, layer relationships, and blocked inferences.
MAD Glossary and Term Index — lookup index for governed terms, analysis pages, and machine governance vocabulary.
MAC — Martial Arts Core Ontology — structural concept namespace.
MAL — Martial Arts Learning Architecture — learning mechanism namespace.
DTM — Development Through Martial Arts — developmental concept namespace.
Analysis Pages — applied interpretation using governed MAD definitions and evidence standards.
Sources and Research Basis — scholarship, research grounding, and evidence documentation.

Attribution

The MAD Project's namespace structure, predicate governance model, relation architecture, and concept definitions were developed for the Martial Arts Definitions Project by David Barkley.

Reuse or adaptation of these structures should acknowledge the Martial Arts Definitions Project as the source.