NIEM to SDC4 Quick Reference Guide

Document Type: Quick Reference (Open Source) Audience: Implementers, developers Status: Draft Version: 1.0 Date: 2025-11-03 Authors: Timothy W. Cook (Founder, Axius SDC, Inc.) w/Claude (Anthropic AI Assistant) Organization: Semantic Data Charter (open source community) License: Creative Commons Attribution 4.0 International (CC BY 4.0)

About This Document: This describes the open SDC4 specification maintained by the Semantic Data Charter. SDCStudio by Axius SDC, Inc. is one commercial implementation of this specification. See ABOUT_SDC4_AND_SDCSTUDIO.md for the distinction between open specifications and commercial tools.

Purpose

Fast lookup guide for mapping NIEM elements and types to SDC4 components. Use this for quick implementation decisions.

For detailed explanations, see:

NIEM_SDC4_TYPE_MAPPING.md - Complete mappings with examples
NIEM_PERSON_TO_SDC4.md - Person-specific patterns

Common NIEM Elements → SDC4 Types

NIEM Element	SDC4 Type	Notes
`nc:PersonBirthDate`	`XdTemporal`	Date value
`nc:PersonName`	`Cluster`	Hierarchical: given, middle, sur
`nc:PersonGivenName`	`XdString`	Simple text
`nc:PersonSurName`	`XdString`	Simple text
`nc:PersonSSNIdentification`	`XdString`	Identifier pattern
`nc:PersonSex`	`XdString`	Use enumeration
`nc:PersonRace`	`XdString`	Use enumeration
`nc:PersonEthnicity`	`XdString`	Use enumeration
`nc:PersonHeightMeasure`	`XdQuantity`	With units
`nc:PersonWeightMeasure`	`XdQuantity`	With units
`nc:PersonAge`	`XdCount`	Integer
`nc:LocationAddress`	`Cluster`	Hierarchical address components
`nc:LocationStreet`	`XdString`	Street address
`nc:LocationCityName`	`XdString`	City name
`nc:LocationState`	`XdString`	State/province
`nc:LocationPostalCode`	`XdString`	ZIP/postal code
`nc:LocationCountry`	`XdString`	Country code
`nc:LocationLatitude`	`XdQuantity`	With degrees units
`nc:LocationLongitude`	`XdQuantity`	With degrees units
`nc:ActivityDate`	`XdTemporal`	Date value
`nc:ActivityStartDate`	`XdTemporal`	Start date
`nc:ActivityEndDate`	`XdTemporal`	End date
`nc:ActivityDescriptionText`	`XdString`	Long text
`nc:ActivityCategoryText`	`XdString`	Category/type
`nc:ActivityIdentification`	`XdString`	Identifier
`nc:DocumentIdentification`	`XdString`	Identifier
`nc:DocumentCreationDate`	`XdTemporal`	Creation date
`nc:DocumentTitle`	`XdString`	Title text
`nc:DocumentDescriptionText`	`XdString`	Description
`nc:ItemName`	`XdString`	Item name
`nc:ItemQuantity`	`XdCount`	Quantity integer
`nc:ItemValue`	`XdQuantity`	With currency units
`nc:ItemDescriptionText`	`XdString`	Description

NIEM Data Types → SDC4 Types

NIEM XML Type	SDC4 Type	Example
`xs:string`	`XdString`	Text data
`xs:int`	`XdCount`	Integers
`xs:integer`	`XdCount`	Large integers
`xs:positiveInteger`	`XdCount`	Positive only
`xs:date`	`XdTemporal`	YYYY-MM-DD
`xs:dateTime`	`XdTemporal`	ISO 8601
`xs:time`	`XdTemporal`	HH:MM:SS
`xs:gYear`	`XdTemporal`	Year only
`xs:boolean`	`XdBoolean`	true/false
`xs:decimal`	`XdQuantity`	With units
`xs:double`	`XdQuantity`	Floating point
`xs:anyURI`	`XdLink`	URLs, URIs
`xs:base64Binary`	`XdFile`	Binary data

NIEM Patterns → SDC4 Patterns

Pattern: Simple Property

NIEM:

<nc:PersonGivenName>John</nc:PersonGivenName>

SDC4:

<!-- Instance -->
<sdc4:ms-sx0a4d8f78722 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Given Name</label>
<xdstring-value>John</xdstring-value>
</sdc4:ms-sx0a4d8f78722>

Schema annotation: Component (ms-sx0a4d8f78722) links to http://niem.gov/niem-core/PersonGivenName via rdfs:isDefinedBy.

Pattern: Complex Type (Hierarchical)

NIEM:

<nc:PersonName>
<nc:PersonGivenName>John</nc:PersonGivenName>
<nc:PersonSurName>Doe</nc:PersonSurName>
</nc:PersonName>

SDC4:

<!-- Instance -->
<sdc4:ms-pu7x1a5c45699 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Person Name</label>

<sdc4:ms-sx0a4d8f78722><!-- Reused Given Name -->
<label>Given Name</label>
<xdstring-value>John</xdstring-value>
</sdc4:ms-sx0a4d8f78722>

<sdc4:ms-ty1b5e9g89733><!-- Surname -->
<label>Surname</label>
<xdstring-value>Doe</xdstring-value>
</sdc4:ms-ty1b5e9g89733>
</sdc4:ms-pu7x1a5c45699>

Schema annotations: Person Name Cluster (ms-pu7x1a5c45699) links to http://niem.gov/niem-core/PersonName. Surname (ms-ty1b5e9g89733) links to http://niem.gov/niem-core/PersonSurName.

Pattern: Measurement with Units

NIEM:

<nc:PersonHeightMeasure>
<nc:MeasureValue>180</nc:MeasureValue>
<nc:LengthUnitCode>cm</nc:LengthUnitCode>
</nc:PersonHeightMeasure>

SDC4:

<!-- Instance -->
<sdc4:ms-uz2c6f0h90744 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Height</label>
<magnitude>180</magnitude>
<units>cm</units>
</sdc4:ms-uz2c6f0h90744>

Schema annotation: Component (ms-uz2c6f0h90744) restricts XdQuantityType and links to http://niem.gov/niem-core/PersonHeightMeasure.

Pattern: Code/Enumeration

NIEM:

<nc:PersonSex>
<nc:SexCode>M</nc:SexCode>
</nc:PersonSex>

SDC4:

<!-- Instance -->
<sdc4:ms-vw3d7g1i01755 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Sex</label>
<xdstring-value>M</xdstring-value>
</sdc4:ms-vw3d7g1i01755>

Schema annotation: Component (ms-vw3d7g1i01755) has enumeration constraint (M=Male, F=Female) and links to http://niem.gov/niem-core/PersonSex.

Pattern: Date/Time

NIEM:

<nc:PersonBirthDate>
<nc:Date>1985-05-15</nc:Date>
</nc:PersonBirthDate>

SDC4:

<!-- Instance -->
<sdc4:ms-ot6w0z4b34688 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Birth Date</label>
<xdtemporal-value>1985-05-15</xdtemporal-value>
</sdc4:ms-ot6w0z4b34688>

Schema annotation: Component (ms-ot6w0z4b34688) restricts XdTemporalType and links to http://niem.gov/niem-core/PersonBirthDate.

Pattern: Identifier

NIEM:

<nc:PersonSSNIdentification>
<nc:IdentificationID>123-45-6789</nc:IdentificationID>
</nc:PersonSSNIdentification>

SDC4:

<!-- Instance -->
<sdc4:ms-qv8y2b6d56700 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>SSN</label>
<xdstring-value>123-45-6789</xdstring-value>
</sdc4:ms-qv8y2b6d56700>

Schema annotation: Component (ms-qv8y2b6d56700) restricts XdStringType and links to http://niem.gov/niem-core/PersonSSNIdentification.

Pattern: Multiple Values (maxOccurs="unbounded")

NIEM:

<nc:PersonName>
<nc:PersonGivenName>John</nc:PersonGivenName>
<nc:PersonGivenName>Michael</nc:PersonGivenName>
</nc:PersonName>

SDC4 Option 1 (List Type):

<!-- Instance -->
<sdc4:ms-wx4e8h2l12766 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Given Names</label>
<xdstringlist-value>John</xdstringlist-value>
<xdstringlist-value>Michael</xdstringlist-value>
</sdc4:ms-wx4e8h2l12766>

Schema annotation: Component (ms-wx4e8h2l12766) restricts XdStringListType and links to http://niem.gov/niem-core/PersonGivenName.

SDC4 Option 2 (Separate Components):

<!-- Instance -->
<sdc4:ms-sx0a4d8f78722 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>First Given Name</label>
<xdstring-value>John</xdstring-value>
</sdc4:ms-sx0a4d8f78722>

<sdc4:ms-sx0a4d8f78722 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Middle Given Name</label>
<xdstring-value>Michael</xdstring-value>
</sdc4:ms-sx0a4d8f78722>

Both instances use the same reusable Given Name component (ms-sx0a4d8f78722).

Pattern: Association (Relationship)

NIEM:

<nc:PersonResidenceAssociation>
<nc:Person ref="person_001"/>
<nc:Location ref="location_001"/>
</nc:PersonResidenceAssociation>

SDC4:

<!-- Instance -->
<sdc4:ms-yz5f9i3m23777 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Person Residence</label>

<sdc4:ms-za6g0j4n34788><!-- Person Reference -->
<label>Person Reference</label>
<xdlink-value>person_001</xdlink-value>
</sdc4:ms-za6g0j4n34788>

<sdc4:ms-ab7h1k5o45799><!-- Location Reference -->
<label>Location Reference</label>
<xdlink-value>location_001</xdlink-value>
</sdc4:ms-ab7h1k5o45799>
</sdc4:ms-yz5f9i3m23777>

Schema annotations: Residence Cluster (ms-yz5f9i3m23777) links to http://niem.gov/niem-core/PersonResidenceAssociation. Person Reference (ms-za6g0j4n34788) links to http://niem.gov/niem-core/Person. Location Reference (ms-ab7h1k5o45799) links to http://niem.gov/niem-core/Location.

Pattern: Augmentation

NIEM:

<nc:Person>
<nc:PersonName>
<nc:PersonFullName>John Doe</nc:PersonFullName>
</nc:PersonName>

<j:PersonAugmentation>
<j:PersonFBIIdentification>
<nc:IdentificationID>FBI-123</nc:IdentificationID>
</j:PersonFBIIdentification>
</j:PersonAugmentation>
</nc:Person>

SDC4 (No separate augmentation namespace):

<!-- Instance -->
<sdc4:ms-ns5v9y3a23677 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Person</label>

<sdc4:ms-bc8i2l6p56800><!-- Full Name -->
<label>Full Name</label>
<xdstring-value>John Doe</xdstring-value>
</sdc4:ms-bc8i2l6p56800>

<sdc4:ms-rw9z3c7e67711><!-- FBI ID - domain augmentation -->
<label>FBI ID</label>
<xdstring-value>FBI-123</xdstring-value>
</sdc4:ms-rw9z3c7e67711>
</sdc4:ms-ns5v9y3a23677>

Schema annotations: Person Cluster (ms-ns5v9y3a23677) links to http://niem.gov/niem-core/PersonType. Full Name (ms-bc8i2l6p56800) links to http://niem.gov/niem-core/PersonFullName. FBI ID (ms-rw9z3c7e67711) links to http://niem.gov/domains/justice/PersonFBIIdentification (domain augmentation - no separate namespace needed).

Domain-Specific Quick Reference

Justice Domain

NIEM Justice Element	SDC4 Type	Ontology URI Pattern
`j:PersonFBIIdentification`	`XdString`	`http://niem.gov/domains/justice/PersonFBIIdentification`
`j:ArrestDate`	`XdTemporal`	`http://niem.gov/domains/justice/ArrestDate`
`j:ChargeDescriptionText`	`XdString`	`http://niem.gov/domains/justice/ChargeDescriptionText`
`j:CourtOrderText`	`XdString`	`http://niem.gov/domains/justice/CourtOrderText`

Emergency Management Domain

NIEM EM Element	SDC4 Type	Ontology URI Pattern
`em:IncidentIdentification`	`XdString`	`http://niem.gov/domains/emergency-management/IncidentIdentification`
`em:ResourceCategoryText`	`XdString`	`http://niem.gov/domains/emergency-management/ResourceCategoryText`
`em:DisasterDeclarationDate`	`XdTemporal`	`http://niem.gov/domains/emergency-management/DisasterDeclarationDate`

Immigration Domain

NIEM Immigration Element	SDC4 Type	Ontology URI Pattern
`im:PassportNumberIdentification`	`XdString`	`http://niem.gov/domains/immigration/PassportNumberIdentification`
`im:VisaStatusCode`	`XdString`	`http://niem.gov/domains/immigration/VisaStatusCode`
`im:EntryDate`	`XdTemporal`	`http://niem.gov/domains/immigration/EntryDate`

Multi-Vocabulary Linking Examples

Link to NIEM + Schema.org

<!-- Instance -->
<sdc4:ms-cd9j3m7q67811 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Name</label>
<xdstring-value>John Doe</xdstring-value>
</sdc4:ms-cd9j3m7q67811>

Schema annotation: Component (ms-cd9j3m7q67811) has multiple rdfs:isDefinedBy links: http://niem.gov/niem-core/PersonName and http://schema.org/name.

Link to NIEM + FHIR + Schema.org

<!-- Instance -->
<sdc4:ms-bg3j6m9q01555 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Birth Date</label>
<xdtemporal-value>1985-05-15</xdtemporal-value>
</sdc4:ms-bg3j6m9q01555>

Schema annotation: Component (ms-bg3j6m9q01555) has multiple rdfs:isDefinedBy links: http://niem.gov/niem-core/PersonBirthDate, http://hl7.org/fhir/Patient.birthDate, and http://schema.org/birthDate.

Link to NIEM + Domain-Specific

<!-- Instance -->
<sdc4:ms-de0k4n8r78822 xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
<label>Case Number</label>
<xdstring-value>CASE-2025-001234</xdstring-value>
</sdc4:ms-de0k4n8r78822>

Schema annotation: Component (ms-de0k4n8r78822) has multiple rdfs:isDefinedBy links: http://niem.gov/domains/justice/CaseNumber and http://example.gov/local-justice/CaseTrackingNumber.

Decision Tree: Choosing SDC4 Type

Is it text/string data?
├─ Yes → Use XdString
│  └─ Does it have enumerated values?
│     ├─ Yes → Add <enumeration> to XdString
│     └─ No → Plain XdString
│
Is it a number?
├─ Integer (whole number)?
│  └─ Use XdCount
├─ Measurement with units?
│  └─ Use XdQuantity
└─ Ordinal (ranked)?
└─ Use XdOrdinal
│
Is it a date/time?
└─ Use XdTemporal
├─ Full date: YYYY-MM-DD
├─ DateTime: ISO 8601
└─ Partial date: Year, Month, etc.

Is it true/false?
└─ Use XdBoolean

Is it a file/binary?
└─ Use XdFile

Is it a URL/reference?
└─ Use XdLink

Is it hierarchical (multiple sub-elements)?
└─ Use Cluster

Does it need multiple values?
└─ Use List type (XdStringList, XdCountList, etc.)

Common Mistakes to Avoid

Mistake 1: Forgetting Ontology References

Wrong (no semantic link in schema):

<!-- Schema without ontology reference -->
<xsd:complexType name="mc-cd9j3m7q67811">
<xsd:annotation>
<xsd:appinfo>
<rdf:Description rdf:about="sdc4:mc-cd9j3m7q67811">
<rdfs:label>Name</rdfs:label>
<!-- Missing rdfs:isDefinedBy! -->
</rdf:Description>
</xsd:appinfo>
</xsd:annotation>
...
</xsd:complexType>

Right (with semantic link):

<!-- Schema with ontology reference -->
<xsd:complexType name="mc-cd9j3m7q67811">
<xsd:annotation>
<xsd:appinfo>
<rdf:Description rdf:about="sdc4:mc-cd9j3m7q67811">
<rdfs:label>Name</rdfs:label>
<rdfs:isDefinedBy rdf:resource="http://niem.gov/niem-core/PersonName"/>
</rdf:Description>
</xsd:appinfo>
</xsd:annotation>
...
</xsd:complexType>

<!-- Instance -->
<sdc4:ms-cd9j3m7q67811>
<label>Name</label>
<xdstring-value>John Doe</xdstring-value>
</sdc4:ms-cd9j3m7q67811>

Mistake 2: Using XdString for Numbers

Wrong (using XdStringType for numeric data):

<sdc4:ms-ef1l5o9s89833>
<label>Age</label>
<xdstring-value>25</xdstring-value><!-- Wrong! Should be numeric -->
</sdc4:ms-ef1l5o9s89833>

Right (using XdCountType for integers):

<!-- Instance -->
<sdc4:ms-fg2m6p0t90844>
<label>Age</label>
<xdcount-value>25</xdcount-value>
</sdc4:ms-fg2m6p0t90844>

Schema annotation: Component (ms-fg2m6p0t90844) restricts XdCountType and links to http://niem.gov/niem-core/PersonAge.

Mistake 3: Missing Units on Measurements

Wrong (missing required units element):

<sdc4:ms-gh3n7q1u01855>
<label>Height</label>
<magnitude>180</magnitude>
<!-- Missing units! XdQuantityType requires units -->
</sdc4:ms-gh3n7q1u01855>

Right (includes required units):

<!-- Instance -->
<sdc4:ms-uz2c6f0h90744>
<label>Height</label>
<magnitude>180</magnitude>
<units>cm</units>
</sdc4:ms-uz2c6f0h90744>

Schema annotation: Component (ms-uz2c6f0h90744) restricts XdQuantityType and links to http://niem.gov/niem-core/PersonHeightMeasure.

Mistake 4: Not Using Cluster for Complex Types

Wrong (flattening hierarchy - loses semantic grouping):

<sdc4:ms-sx0a4d8f78722>
<label>Given Name</label>
<xdstring-value>John</xdstring-value>
</sdc4:ms-sx0a4d8f78722>
<sdc4:ms-ty1b5e9g89733>
<label>Surname</label>
<xdstring-value>Doe</xdstring-value>
</sdc4:ms-ty1b5e9g89733>
<!-- No clear relationship between given name and surname -->

Right (preserving hierarchy with Cluster):

<!-- Instance -->
<sdc4:ms-pu7x1a5c45699>
<label>Person Name</label>

<sdc4:ms-sx0a4d8f78722><!-- Given Name -->
<label>Given Name</label>
<xdstring-value>John</xdstring-value>
</sdc4:ms-sx0a4d8f78722>

<sdc4:ms-ty1b5e9g89733><!-- Surname -->
<label>Surname</label>
<xdstring-value>Doe</xdstring-value>
</sdc4:ms-ty1b5e9g89733>
</sdc4:ms-pu7x1a5c45699>

Schema annotation: Person Name Cluster (ms-pu7x1a5c45699) restricts ClusterType and links to http://niem.gov/niem-core/PersonName, grouping related name components.

Additional Resources

Complete References:

NIEM_SDC4_TYPE_MAPPING.md - All NIEM types with detailed examples
NIEM_PERSON_TO_SDC4.md - Person modeling patterns
NIEM_LOCATION_TO_SDC4.md - Location patterns
NIEM_ACTIVITY_TO_SDC4.md - Activity patterns

Strategic Context:

NIEM_OVERVIEW.md - Introduction to NIEM and SDC4
NIEM_SEMANTICS_PROBLEM.md - Why separation matters
NIEM_GOVERNMENT_WIDE_VISION.md - Path to "all of government"

Document Navigation: ← Overview | Complete Mapping Reference →

About This Documentation

This document describes the open SDC4 specification maintained by the Semantic Data Charter community.

Open Source:

Specification: https://semanticdatacharter.com
GitHub: https://github.com/SemanticDataCharter
License: CC BY 4.0

Commercial Implementation:

SDCStudio: https://axius-sdc.com (by Axius SDC, Inc.)

See ABOUT_SDC4_AND_SDCSTUDIO.md for details.

*This document is part of the SDC4 Integration Guide series.*

*Author: Timothy W. Cook (Founder, Axius SDC, Inc.) w/Claude (Anthropic AI Assistant)*

*License: Creative Commons Attribution 4.0 International (CC BY 4.0)*