SHAMIL FOUNDATION
Open Knowledge Standards

SHAMIL™

A Structured Notation Standard for Knowledge Graph Entity Representation
Subject ·Hierarchy · Attribute · Method · Interaction ·Link

Version 1.0 — Core Standard (Schema.org Independent)
March 2026

Search Sciences™ Research Programme | Younis Group
Mohammed Younis, Chief Scientist

Canonical Context: https://shamil.foundation/context/v1-0/shamil.jsonld
Latest pointer: https://shamil.foundation/shamil.jsonld

Publication Note

SHAMIL™ is published as a working paper within the Search Sciences™ Research Programme, operated by Younis Group Ltd under the governance of Mohammed Younis, Chief Scientist. This document is the Version 1.0 Core Standard — the base notation standard that operates without any Schema.org dependency. Schema.org interoperability is addressed in the SHAMIL™ Schema.org Extension, published separately, which is designed as a plugin layer on top of this core.

This version defines the core library of the SHAMIL notation. It defines the grammar, the context file, the conformance rules, and the entity file structure. Vocabulary plugins — Schema.org, sector-specific ontologies, domain extensions — sit on top of it. The core standard does not change when plugins are added.

The Four Scholars — Governing Intellectual PremiseThe intellectual foundations of the Search Sciences™ Research Programme are grounded in the Islamic scholarly tradition of verification, classification, and systematic reasoning. Imam Al-Bukhari, Al-Farabi, Al-Khwarizmi, and Ibn al-Haytham are not background references. They are the governing intellectual premise from which this programme derives its core principles. Their removal from any document produced under this programme is the precise failure mode — Algorithmic Flattening — that this programme exists to document and address.

This specification should be read alongside: The Verified Source Protocol and the Future of Information Science; The Admissibility Problem in AI-Mediated Information Systems (White Paper No. 1); and Algorithmic Flattening and Lossy Semantic Compression in Large Language Models.

Abstract

The contemporary digital information environment presents a structural failure at the knowledge layer. Entities — organisations, persons, products, concepts, places — exist across search engines, large language models, and knowledge graph systems in a condition of semantic inconsistency, unverified attribution, and unstructured representation. AI systems cannot distinguish authoritative entity descriptions from optimised imitations because no formal mechanism exists for encoding entity knowledge in a form that is simultaneously human-authorable, machine-convertible, and governance-ready.

SHAMIL™ — Subject, Hierarchy, Attribute, Method, Interaction, Link — is a structured notation standard that addresses this failure at its foundation. SHAMIL™ provides a human-readable, mnemonic grammar for encoding entity nodes in knowledge graphs, with deterministic conversion pathways to JSON-LD 1.1, RDF triple notation, and SHACL validation shapes. Every entity created using the SHAMIL™ notation is expressed as a JSON-LD file named following the convention [entityname]-shamil.jsonld, placed in the head of a webpage, and immediately readable by systems capable of processing JSON-LD structured data — without dependency on any external authority framework or vocabulary extension.

This document specifies the core SHAMIL™ standard. It is vocabulary-agnostic. It does not depend on Schema.org. Vocabulary integration — Schema.org, sector ontologies, domain-specific extensions — is provided through a plugin architecture described in companion extension documents. The core standard provides the grammar. Extensions provide the vocabulary. Neither requires the other to function.

The intellectual lineage of this standard traces directly to the isnad verification methodology of Imam Al-Bukhari (810–870 CE), the classification science of Al-Farabi (872–950 CE), the systematic resolution methods of Al-Khwarizmi (780–850 CE), and the evidence-based epistemology of Ibn al-Haytham (965–1040 CE). These foundations are structural, not decorative.

1. Intellectual Foundations

The principles that govern SHAMIL™ — provenance verification, hierarchical classification, systematic attribute specification, governed action, relational mapping, and external linking — are not derived from contemporary computer science alone. They have an intellectual genealogy that precedes the semantic web by more than a millennium, and that genealogy is the governing intellectual premise of the Search Sciences™ Research Programme.

1.1 Imam Al-Bukhari (810–870 CE) — Interaction and Link

Al-Bukhari formalised the principle that a claim is only as trustworthy as the integrity of its chain of attribution. His isnad methodology — the systematic verification of every link in a chain of transmission — is the direct intellectual ancestor of the L component as the carrier of verifiable external identity, and of the I component as the declaration of the relationships through which attribution chains are constructed. Al-Bukhari did not evaluate claims on content alone. He evaluated the verified authority of every person in the transmission chain. SHAMIL™ applies this principle structurally: every node carries its chain of attribution in L, available for verification when authority is sought.

1.2 Al-Farabi (872–950 CE) — Hierarchy

Al-Farabi developed the systematic classification of the sciences, establishing that knowledge must be organised hierarchically to avoid ambiguity and to enable reliable inference across domains. His Ihsa al-Ulum (Enumeration of the Sciences) established that every domain of knowledge has a proper place within a structured order. The H component of SHAMIL™ is a direct application of this principle. An entity without a declared class position is semantically ambiguous. An entity with a precisely declared ontological classification is unambiguous and inferentially reliable.

1.3 Al-Khwarizmi (780–850 CE) — Method

Al-Khwarizmi established systematic methods for resolving unknowns through defined procedures. Unknowns were not approximated — they were derived lawfully through stated rules or acknowledged as unresolvable within the available system. The M component of SHAMIL™ is the direct expression of this principle: entity capabilities are declared as structured, named procedures rather than inferred behaviours. Al-Khwarizmi gave the world the algorithm. The algorithm, a millennium later, is erasing Al-Khwarizmi. SHAMIL™ is, in part, the structured corrective to that erasure.

1.4 Ibn al-Haytham (965–1040 CE) — Attribute

Ibn al-Haytham formalised the scientific method — repeatability, falsifiability, and evidence-based validation — centuries before its European formalisation. SHAMIL™ nodes are designed to be repeatable: the same entity described by different authors following the notation standard must produce structurally equivalent representations. They are designed to be falsifiable: SHACL shapes derived from SHAMIL™ node definitions enable systematic verification. And they are designed to be evidence-based: every attribute in the A component is a declared, verifiable claim.

Axiom 1: Knowledge Has a ChainThe trustworthiness of an entity representation is not a function of its content alone. It is a function of the verifiable integrity of its chain of attribution. SHAMIL™ encodes that chain as a structural feature of every node, not as optional metadata.

2. The SHAMIL™ Grammar

SHAMIL™ defines six structural components. S and H are required in every conformant entity. A, M, I, and L are optional — their inclusion depends on the entity type and deployment context. The ordering of component declarations is fixed: S must appear first, H must follow immediately. Thereafter, A, M, I, and L may appear in any order, but canonical ordering (A, then M, then I, then L) is recommended practice.

Component	Key	Required	Maps to	Scholar ancestor
Subject	S	Required	shamil:Subject · @id carries the canonical URI	—
Hierarchy	H	Required	rdf:type · @type · sh:targetClass	Al-Farabi
Attribute	A	Optional	shamil:Attribute container · sh:property	Ibn al-Haytham
Method	M	Optional	Capability declaration · AMANAH™ governance	Al-Khwarizmi
Interaction	I	Optional	RDF object properties · owl:ObjectProperty	Imam Al-Bukhari
Link	L	Optional	owl:sameAs · External identity chain	Imam Al-Bukhari

Conformance note on mandatory components
S and H are mandatory because an entity without identity (S) is not an entity, and an entity without classification (H) is semantically incomplete and cannot be reliably reasoned over. A, M, I, and L are optional because not every entity type requires all four: a historical scholar entity may have no M declarations; a stub entity may have no I declarations at the time of authorship; a private entity may have no L declarations. A SHAMIL™ node without L declarations carries no external provenance chain and cannot be VSP-verified.

2.1 S — Subject

Fix applied — S mapping: S does not map to @id. This section has been corrected.Earlier drafts stated ‘S maps to: rdf:subject · JSON-LD @id’. This was incorrect. In SHAMIL™ entity files, @id carries the canonical resolvable URI of the entity node, while S carries the human-readable subject label. They are distinct fields. S maps to shamil:Subject. The canonical identifier is expressed using JSON-LD @id.
Incorrect (removed): ‘Maps to: rdf:subject · JSON-LD @id’Correct (this version): ‘Maps to: shamil:Subject. The canonical identifier of the entity node is expressed using JSON-LD @id.’

Required. Exactly one. Maps to: shamil:Subject. The canonical identifier of the entity node is expressed using JSON-LD @id.

The Subject is the human-readable canonical name of the entity being described. It must be unique within the graph context in which it is deployed. The Subject is what the entity file is named after: a SHAMIL™ node whose Subject is ‘Rima’s Bakery’ produces an entity file named rimasbakery-shamil.jsonld.

The @id field — distinct from S — is the globally resolvable URI that uniquely identifies this node in the graph. Implementers must not attempt to derive @id programmatically from S. They are independent fields serving different purposes: S is human-readable identity; @id is machine-resolvable graph identity.

2.2 H — Hierarchy

Required. One or more. Maps to: rdf:type · JSON-LD @type · sh:targetClass

The ontological classification of the subject. Hierarchy declares the entity type and its position within the broader class taxonomy. At least one H value is required. Multiple H values are permitted where an entity belongs to multiple classes. H values reference the vocabulary active in the deployment context: SHAMIL™ native vocabulary for base deployment, Schema.org types when the Schema.org extension is active, domain ontology classes when a sector extension is active.

Vocabulary note: H values using the shamil: prefix (e.g. shamil:Organization, shamil:Person) expand to IRIs under https://shamil.foundation/vocab/. The core vocabulary defining these class terms is maintained at that base URI. Where a class is not yet defined in the core vocabulary, H values may use unprefixed local names, clearly documented in the entity file. Vocabulary extensions (Schema.org, sector ontologies) define their own class terms independently.

2.3 A — Attribute

Optional. Zero or more. Maps to: shamil:Attribute container object

Verifiable properties of the entity, expressed as key-value pairs within the A container object. In JSON-LD serialisation, A is a single property whose value is an object containing key-value pairs. This means A does not generate direct RDF subject-predicate-object triples from its contents in the base context — it generates a single shamil:Attribute node containing the key-value pairs as properties of that node. Vocabulary extensions may promote specific A keys to direct RDF predicates within their extended context. Attributes must be declarable, verifiable, and stable. They must not be promotional descriptions.

Design note — Attribute container and blank nodesIn RDF serialisation, the Attribute container is typically represented as a blank node. This means attribute values are attached to an intermediary node rather than directly to the entity. This is a deliberate design choice that enables metadata to be attached to the attribute container itself.
Consequence for query authors: a SPARQL query such as ‘find all entities with founded = 2020’ must traverse the blank node pattern (entity → shamil:Attribute → node → founded → 2020) rather than querying the triple directly (entity → founded → 2020). Vocabulary extensions that promote specific A keys to direct RDF predicates restore direct query behaviour for those promoted keys.
This behaviour is by design for the base standard.

2.4 M — Method

Optional. Zero or more. Maps to: AMANAH™ Capability Declaration Layer

Declared executable capabilities of the entity. An M declaration is a formal statement of what the entity is authorised to do — not an instruction to do it. M declarations define: the action name, the action type (from the Action Type Registry in Section 9), the required authority level (from the Authority Level Registry in Section 9), and optionally the governance policy reference under which the action may be executed. M declarations are not autonomous triggers. They are governed capability statements.

AMANAH™ dependency noteM declarations describe what an entity may do. Whether and how those capabilities are executed is governed by AMANAH™, the capability governance layer of the Search Sciences™ Research Programme. AMANAH™ is defined in a companion document. Without an AMANAH™ deployment, M declarations remain valid structured metadata — they describe capability but carry no enforcement mechanism. The update action type, in particular, requires AMANAH™ to have operational meaning: it declares that the entity’s own SHAMIL™ node may be modified, but the mechanism for that modification is defined in the AMANAH™ specification, not in this document.

2.5 I — Interaction

Fix applied — field name consistency: Section 2.5 text corrected to use ‘interactionType’ throughout.Earlier drafts referred to the mandatory fields of an I declaration as ‘type’ and ‘target’. The field name in the context and all entity file examples is ‘interactionType’, not ‘type’. Using ‘type’ as a plain key in an I object would produce an unmapped JSON property that no JSON-LD processor would treat as a graph predicate. This section now uses the correct field name ‘interactionType’ throughout.

Optional. Zero or more. Maps to: RDF object properties · owl:ObjectProperty

Relationship edges connecting the subject entity to other entities within the graph. Each I declaration is an object with two mandatory fields: interactionType (the relationship predicate, resolved via the context to shamil:interactionType) and target (the URI of the related entity, resolved via the context as an IRI reference). Without I declarations, SHAMIL™ nodes are isolated descriptions. With I declarations, they form a structured, traversable knowledge architecture.

Design note — Reified interaction model
In the base SHAMIL™ context, relationship predicates are stored as values of interactionType rather than as direct RDF predicates. This is relationship reification.
Standard RDF practice would produce: entity → locatedIn → entitySHAMIL™ base produces: entity → shamil:Interaction → node → interactionType → ‘locatedIn’ → target → entity
This design is intentional. Reification allows metadata — such as temporality — to be attached to the relationship itself. The trade-off is that SPARQL queries must traverse the reification layer. Vocabulary extensions may promote specific interactionType values to direct RDF predicates, restoring direct-triple behaviour for those relationships where the metadata attachment is not required.

2.6 L — Link

Optional. Zero or more. Maps to: owl:sameAs · External identity registries · VSP identity chain

External identifiers and URIs that connect the SHAMIL™ node to external information systems, authority registries, and identity frameworks. L values are URI strings. L declarations should include, where applicable: the canonical website URI, the Wikidata QID, sector-specific regulatory identifiers, and decentralised identifiers (DIDs) where VSP-compliant deployment is intended.

3. Formal Grammar

The following BNF grammar defines the SHAMIL™ notation standard formally. A compliant SHAMIL™ processor must accept all inputs conforming to this grammar and must reject inputs that violate it. In JSON-LD serialisation, AttributeDecl entries are grouped inside the A object as key-value pairs; the BNF models the authored notation form prior to serialisation.

SHAMILNode     ::= SubjectDecl HierarchyDecl+ AttributeDecl*
                   MethodDecl* InteractionDecl* LinkDecl*


SubjectDecl    ::= 'S:' WhiteSpace Identifier
HierarchyDecl  ::= 'H:' WhiteSpace ClassReference
AttributeDecl  ::= 'A:' WhiteSpace Key '=' Value ['^^' Datatype] [Unit]
MethodDecl     ::= 'M:' WhiteSpace ActionName '(' ActionType ')'
                   ['[' GovernanceRef ']'] ['@' AuthorityLevel]
InteractionDecl::= 'I:' WhiteSpace RelationType '=' TargetIdentifier
                   ['[' Temporality ']'] ['@' AuthorityRef]
LinkDecl       ::= 'L:' WhiteSpace URI


Identifier     ::= String | URI
ClassReference ::= VocabPrefix ':' ClassName | ClassName
Key            ::= AlphanumericString
Value          ::= String | Number | URI | Boolean
Datatype       ::= XSDType | CustomType
ActionName     ::= AlphanumericString
ActionType     ::= 'read' | 'write' | 'transact' | 'notify'
                 | 'file' | 'update' | DomainActionType
GovernanceRef  ::= String
AuthorityLevel ::= 'public' | 'verified' | 'institutional' | 'sovereign'
RelationType   ::= VocabPrefix ':' PredicateName | PredicateName
TargetIdentifier ::= URI
Temporality    ::= DateRange | 'current' | 'historical'
DateRange      ::= ISO8601Date '/' ISO8601Date
ISO8601Date    ::= YYYY '-' MM '-' DD
Unit           ::= '[' UnitString ']'
UnitString     ::= AlphanumericString
URI            ::= RFC3986URI

Fix applied — DateRange and Unit defined: BNF grammar now fully specifies all terminals.Earlier versions of the grammar included ‘Temporality ::= DateRange | current | historical’ and an optional [Unit] in AttributeDecl, but neither DateRange nor Unit were formally defined anywhere in the specification. This left implementers with undefined grammar tokens.
DateRange is now defined as: ISO8601Date ‘/’ ISO8601Date — following ISO 8601 interval notation (e.g. 2010-01-01/2020-12-31). Processors that encounter a DateRange value in temporality should treat the two dates as the start and end of the relationship’s validity period.
Unit is now defined as: ‘[‘ UnitString ‘]’ where UnitString is a free-text label. Unit is an optional annotation on attribute values (e.g. A: height = 42 [metres]). It is a notation-layer hint and does not generate a separate RDF triple in the base context. A future units extension may formalise a unit registry.

The ordering of component declarations is fixed: S must appear first, H must follow immediately. A, M, I, and L may thereafter appear in any order. A conformant processor must accept interleaved declarations but should normalise to canonical ordering upon ingestion.

4. The Canonical Context File

The canonical machine representation of SHAMIL™ entities is JSON-LD 1.1. The versioned context file for this release is permanently hosted at:

https://shamil.foundation/context/v1-0/shamil.jsonld

The unversioned latest pointer resolves to the current release and is the URI used in all entity files for this version:

https://shamil.foundation/shamil.jsonld

Both URIs serve the same content for Version 1.0. The versioned URI is the permanent, immutable record. The unversioned URI is the latest pointer and will advance with future versions. Entity files authored against Version 1.0 may reference either URI; the versioned URI is recommended for long-term stability. The server must return Content-Type: application/ld+json for both.

Launch dependency — context URI must be live before entity files are publishedThe context URIs listed above are referenced by every conformant SHAMIL™ entity file. If either URI returns a non-200 HTTP response, or returns Content-Type: text/html instead of Content-Type: application/ld+json, all entity files referencing those URIs will fail to process correctly in JSON-LD processors.
This is a hard launch dependency. Entity files must not be published until both URIs are live and returning the correct content type. The context file content is defined in Section 4.1. Verify with: curl -I https://shamil.foundation/shamil.jsonld

4.1 Context File Definition

{
  "@context": {
    "@version": 1.1,
    "shamil": "https://shamil.foundation/vocab/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",


    // Entity type alias — resolves "Entity" to shamil:Entity
    // Use "@type": "Entity" in entity files (not "@type": "shamil:Entity")
    "Entity": "shamil:Entity",


    // Subject — the human-readable label of the node
    // Note: @id carries the canonical URI. S carries the label.
    "S": { "@id": "shamil:Subject" },


    // Hierarchy — ontological classification
    "H": {
      "@id": "shamil:Hierarchy",
      "@container": "@set"
    },

    // Attribute — verifiable property container
    "A": { "@id": "shamil:Attribute" },


    // Method — capability declaration set
    "M": {
      "@id": "shamil:Method",
      "@container": "@set"
    },


    // Method sub-terms — mapped so they are typed in RDF
    "name":      { "@id": "shamil:methodName" },
    "type":      { "@id": "shamil:actionType" },
    "authority": { "@id": "shamil:authority" },


    // Interaction — relationship edge set
    // interactionType stores the predicate as a value (reified)
    // target is @type: @id so processors generate a graph edge
    "I": {
      "@id": "shamil:Interaction",
      "@container": "@set"
    },
    "interactionType": { "@id": "shamil:interactionType" },
    "target":          { "@id": "shamil:target", "@type": "@id" },
    "temporality":     { "@id": "shamil:temporality" },


    // Link — external identity and provenance chain
    "L": {
      "@id": "shamil:Link",
      "@container": "@set",
      "@type": "@id"
    }
  }
}

Fix applied — Method sub-terms added to context: name and type are now formally mapped.Earlier versions of the context defined only ‘authority’ as a Method sub-term. The fields ‘name’ and ‘type’ were used in all entity file examples but were not mapped in the context, meaning they were treated as plain JSON properties by JSON-LD processors rather than typed RDF terms.
This version adds: “name”: { “@id”: “shamil:methodName” } and “type”: { “@id”: “shamil:actionType” }. This ensures all three Method sub-terms are semantically defined and will be processed correctly by JSON-LD processors.

4.2 Key Design Decisions

Entity alias. The context defines “Entity”: “shamil:Entity” as an alias. Entity files must use “@type”: “Entity” — not “@type”: “shamil:Entity”. Both resolve to the same IRI, but using the prefixed form in the entity file body bypasses the alias defined in the context, producing inconsistent serialisation. The alias exists precisely so that entity authors write Entity, not the namespace prefix.

S and @id separation. S carries the human-readable subject label (mapped to shamil:Subject). The @id field carries the canonical, globally resolvable URI of the entity node. These are always distinct fields. Implementers must not derive @id from S programmatically.

Interaction terms. The target term is mapped with “@type”: “@id” so that JSON-LD processors treat its value as an IRI reference and generate a graph edge, not a plain string literal. The interactionType term carries the relationship predicate value as a string (reified model — see design note in Section 2.5). These mappings are necessary for I declarations to produce valid RDF object properties.

Link type. L values carry “@type”: “@id” on the container, ensuring all L values are treated as IRI references, not strings.

Attribute semantics. A is defined as a single property (shamil:Attribute) whose value is a container object. In the base context, A does not generate direct RDF subject-predicate-object triples. It generates a shamil:Attribute node (typically a blank node) containing the key-value pairs as properties of that node. See Section 2.3 design note for query implications. This behaviour is by design for the base standard.

4.3 Vocabulary IRIs

Term	IRI
Entity	https://shamil.foundation/vocab/Entity
S (Subject)	https://shamil.foundation/vocab/Subject
H (Hierarchy)	https://shamil.foundation/vocab/Hierarchy
A (Attribute)	https://shamil.foundation/vocab/Attribute
M (Method)	https://shamil.foundation/vocab/Method
I (Interaction)	https://shamil.foundation/vocab/Interaction
L (Link)	https://shamil.foundation/vocab/Link
interactionType	https://shamil.foundation/vocab/interactionType
target	https://shamil.foundation/vocab/target
temporality	https://shamil.foundation/vocab/temporality
authority	https://shamil.foundation/vocab/authority
name (methodName)	https://shamil.foundation/vocab/methodName
type (actionType)	https://shamil.foundation/vocab/actionType

4.4 Stability Rule

Once the Version 1.0 context file is public, the meaning of existing terms must not change. New terms may be added in future versions under new versioned context URIs. Existing terms are immutable. This ensures all graphs built against SHAMIL™ v1.0 remain valid indefinitely, and that the versioned context URI https://shamil.foundation/context/1.0/shamil.jsonld serves identical content permanently.

5. The Entity File

The primary output of the SHAMIL™ notation process for web deployment is an entity file. The entity file is the practical expression of the standard — the file an organisation, researcher, or institution places on its website to make its entity description directly readable by systems capable of processing JSON-LD structured data.

5.1 File Naming Convention

Mandatory rule: [entityname]-shamil.jsonld — lowercase, hyphen-separated, ending in -shamil.jsonld.

[entityname] is a normalised, lowercase, hyphen-separated identifier derived from the entity’s Subject declaration. The suffix -shamil identifies the file as a SHAMIL™-structured entity node. The extension .jsonld declares the file as a JSON-LD document. Both elements are mandatory.

Entity name	Correct filename	Non-conformant
Rima’s Bakery	rimasbakery-shamil.jsonld	rimasbakery.jsonld
Younis Group	younis-group-shamil.jsonld	younis-group.json
Al-Khwarizmi	al-khwarizmi-shamil.jsonld	alkhwarizmi.jsonld
SHAMIL Foundation	shamil-foundation-shamil.jsonld	shamil.jsonld
Genomics Res. Inst. Iceland	genomics-research-institute-iceland-shamil.jsonld	gri-iceland.jsonld

5.2 Canonical Entity File Structure

A conformant SHAMIL™ entity file is a valid JSON-LD 1.1 document. The @type field must use the Entity alias defined in the context — not the prefixed form shamil:Entity:

{
  "@context": "https://shamil.foundation/shamil.jsonld",
  "@type": "Entity",
  "@id": "https://yoursite.com/entities/your-entity-name",
  "S": "Your Entity Name",
  "H": [
    "shamil:YourEntityType"
  ],
  "A": {
    "key": "value",
    "key2": "value2"
  },
  "M": [
    {
      "name": "actionName",
      "type": "read | write | transact | notify | file | update",
      "authority": "public | verified | institutional | sovereign"
    }
  ],
  "I": [
    {
      "interactionType": "relationshipType",
      "target": "https://target-entity-uri",
      "temporality": "current | historical | YYYY-MM-DD/YYYY-MM-DD"
    }
  ],
  "L": [
    "https://your-canonical-site.com"
  ]
}

5.3 Deployment

The entity file is embedded within the <head> section of a web page as an inline JSON-LD script block. The file content is inlined — not referenced via a src attribute. External script references are not followed by JSON-LD processors.

<script type="application/ld+json">
{
  "@context": "https://shamil.foundation/shamil.jsonld",
  "@type": "Entity",
  "@id": "https://yoursite.com/entities/your-entity",
  "S": "Your Entity Name",
  "H": ["shamil:Organization"],
  "A": { "founded": "2020", "country": "United Kingdom" },
  "L": ["https://yoursite.com"]
}
</script>

Independence principleThe entity file is complete the moment it is authored. No application, no verification body, no institutional relationship is required for a SHAMIL™ entity file to be valid and readable by JSON-LD processors. VSP verification and Schema.org extension are optional enhancements. Neither is a condition of use.

6. Worked Examples

The following examples demonstrate conformant SHAMIL™ entity files across entity types. All examples use only the core SHAMIL™ context. No Schema.org vocabulary is referenced. Note the use of “@type”: “Entity” (the alias) and interactionType / target (the mapped I sub-terms) throughout.

6.1 Local Business Entity — Rima’s Bakery

{
  "@context": "https://shamil.foundation/shamil.jsonld",
  "@type": "Entity",
  "@id": "https://rimasbakery.co.uk/entities/rimasbakery",
  "S": "Rima's Bakery",
  "H": [
    "shamil:LocalBusiness",
    "shamil:FoodEstablishment"
  ],
  "A": {
    "address": "14 Columbia Road, London E2 7RG",
    "telephone": "+44 20 7729 4321",
    "openingHours": "Sat-Sun 08:00-15:00",
    "founded": "2015",
    "priceRange": "£",
    "cuisine": "Bakery, Middle Eastern"
  },
  "M": [
    { "name": "PlaceOrder",        "type": "transact", "authority": "public"   },
    { "name": "MakeReservation",   "type": "transact", "authority": "public"   },
    { "name": "UpdateTradingHours","type": "write",    "authority": "verified" }
  ],
  "I": [
    {
      "interactionType": "locatedIn",
      "target": "https://www.wikidata.org/wiki/Q21690038",
      "temporality": "current"
    },
    {
      "interactionType": "memberOf",
      "target": "https://shamil.foundation/entities/columbia-road-market-association",
      "temporality": "current"
    }
  ],
  "L": [
    "https://rimasbakery.co.uk"
  ]
}

6.2 Person Entity — Al-Khwarizmi (Historical Scholar)

The structural corrective to Algorithmic Flattening. A first-class SHAMIL™ entity node for a historical scholar. His presence in the graph is the corrective. Erasure requires explicit deletion of a structured node — not editorial oversight.

{
  "@context": "https://shamil.foundation/shamil.jsonld",
  "@type": "Entity",
  "@id": "https://shamil.foundation/entities/al-khwarizmi",
  "S": "Al-Khwarizmi",
  "H": [
    "shamil:Person",
    "shamil:MathematicalScientist",
    "shamil:IslamicGoldenAgeScholar"
  ],
  "A": {
    "fullName": "Muhammad ibn Musa al-Khwarizmi",
    "birthYear": "780",
    "deathYear": "850",
    "era": "Islamic Golden Age",
    "fields": "Mathematics, Algebra, Astronomy, Geography",
    "keyContribution": "Algebra; systematic algorithmic reasoning; gave the world the algorithm",
    "institutionalAffiliation": "House of Wisdom, Baghdad"
  },
  "I": [
    {
      "interactionType": "intellectualAncestorOf",
      "target": "https://shamil.foundation/entities/shamil-method-component",
      "temporality": "historical"
    },
    {
      "interactionType": "workedAt",
      "target": "https://shamil.foundation/entities/house-of-wisdom",
      "temporality": "historical"
    },
    {
      "interactionType": "contemporaryOf",
      "target": "https://shamil.foundation/entities/al-kindi",
      "temporality": "historical"
    }
  ],
  "L": [
    "https://www.wikidata.org/wiki/Q9028",
    "https://shamil.foundation/entities/al-khwarizmi"
  ]
}

6.3 Organisation Entity — Younis Group

{
  "@context": "https://shamil.foundation/shamil.jsonld",
  "@type": "Entity",
  "@id": "https://younisgroup.co.uk/entities/younis-group",
  "S": "Younis Group",
  "H": [
    "shamil:Organization",
    "shamil:InformationScienceConsultancy"
  ],
  "A": {
    "legalName": "Younis Group Ltd",
    "founded": "2020",
    "country": "United Kingdom",
    "programme": "Search Sciences Research Programme",
    "website": "https://younisgroup.co.uk"
  },
  "M": [
    { "name": "publishResearch",    "type": "notify",   "authority": "public"   },
    { "name": "conductConsultancy", "type": "transact", "authority": "verified" }
  ],
  "I": [
    {
      "interactionType": "foundedBy",
      "target": "https://younisgroup.co.uk/entities/mohammed-younis"
    },
    {
      "interactionType": "stewardOf",
      "target": "https://shamil.foundation/entities/shamil-standard"
    }
  ],
  "L": [
    "https://younisgroup.co.uk",
    "https://shamil.foundation/entities/younis-group"
  ]
}

7. Conformance

A SHAMIL™ entity description is conformant with this specification if all of the following conditions are satisfied:

Rule	Requirement
C1	S (Subject) is present with exactly one value.
C2	H (Hierarchy) is present with one or more values.
C3	A, M, I, and L are optional. Where present, each must conform to the grammar defined in Sections 2 and 3.
C4	The @context field references https://shamil.foundation/shamil.jsonld or the versioned URI https://shamil.foundation/context/1.0/shamil.jsonld as a single string value.
C5	The entity file is a valid JSON-LD 1.1 document.
C6	The entity carries a canonical @id as a globally resolvable URI.
C7	The entity file is named [entityname]-shamil.jsonld.
C8	All I (Interaction) target values are valid URIs that return HTTP 200 or 303 when dereferenced at time of validation, or are registered entity identifiers within the deployment graph, or are valid under a non-HTTP identifier scheme (DID, URN, IPFS CID, or equivalent). Targets that are resolvable graph-internal references declared at authoring time but not yet deployed are exempt pending deployment.
C9	All M (Method) declarations specify name, type, and authority. Type must be a value from the Action Type Registry (Section 9.2). Authority must be a value from the Authority Level Registry (Section 9.3).
C10	The @type field uses the value “Entity” (the context alias) — not “shamil:Entity”.

Fix applied — C8 revised: Conformance rule C8 now correctly scoped to validation time.The earlier version of C8 required all I target URIs to return HTTP 200 or 303 without qualification. This was unenforceable at authoring time (entities reference targets not yet deployed), excluded valid non-HTTP identifier schemes (DIDs, URNs, IPFS), and caused the specification’s own worked examples to fail conformance (e.g. the Al-Khwarizmi entity references targets that may not yet be deployed).
C8 is now qualified: ‘at time of validation’, includes non-HTTP identifier schemes, and provides an explicit exemption for graph-internal references declared but not yet deployed.

A conformant SHAMIL™ entity file that additionally references the Schema.org extension context is conformant with both this specification and the SHAMIL™ Schema.org Extension. Conformance with the extension is a superset of conformance with the core standard.

8. Conversion Specifications

The following tables define the deterministic mapping between SHAMIL™ components and their target format equivalents. A compliant SHAMIL™ processor must implement these mappings without deviation.

8.1 SHAMIL™ to JSON-LD Mapping

SHAMIL™ Component	JSON-LD Construct	Notes
S (Subject)	shamil:Subject + @id	S is the human-readable label mapped to shamil:Subject. @id is the canonical entity URI, distinct from S. Both are always present.
H (Hierarchy)	@type array	Each H value becomes a member of the @type array. The @type value “Entity” is always present.
A (Attribute)	shamil:Attribute object	The A object is the value of the shamil:Attribute property. Its key-value pairs are properties of the Attribute node (typically a blank node). Not direct RDF triples in the base context.
M (Method)	shamil:Method array	Each M declaration becomes an object with name (shamil:methodName), type (shamil:actionType), authority, and optional governance fields.
I (Interaction)	shamil:Interaction array	Each I declaration: interactionType carries the predicate as a value (reified), target is an IRI reference (@type: @id), temporality is a plain string or ISO 8601 interval.
L (Link)	shamil:Link array	Each L value is an IRI reference. In VSP deployments, the DID from L takes precedence as @id.

8.2 SHAMIL™ to SHACL Shape Generation

Every SHAMIL™ node definition generates a SHACL NodeShape that validates instances of that entity type. Generation rules are deterministic.

SHAMIL™ Component	SHACL Construct	Constraint Generated
S (Subject)	sh:NodeShape target	sh:targetClass derived from H values
H (Hierarchy)	sh:targetClass	Validates that entity instances declare the required class
A (Attribute)	sh:property	sh:path, sh:datatype, sh:minCount per attribute declaration
M (Method)	sh:property (capability)	Validates action types against Section 9.2 registry; authority against Section 9.3 registry
I (Interaction)	sh:property (object)	Validates that target values are valid IRIs returning HTTP 200 or 303 at time of validation
L (Link)	sh:property (URI)	Validates that L values are valid IRIs conforming to RFC 3986

9. Method Declarations and Registries

The Method component requires dedicated treatment. It is the most novel component of the notation standard. This section also formally defines the registries that govern valid values for M declarations and I declarations.

9.1 M as Capability Declaration

An M declaration is a formal statement of what an entity is authorised to do. It is not an instruction to do it.

Architectural principleM declares what an entity may do. AMANAH™ governs whether it does it.
The distinction between capability and execution is the foundation of safe agentic AI architecture.

9.2 Action Type Registry

The following values constitute the normative Action Type Registry for Version 1.0. M declarations must use one of these values in the type field, or a domain-specific type registered in an approved sector extension.

Action type	Definition
read	Retrieval of information from external systems or registries. No state change is effected.
write	Creation or modification of a record associated with the entity. State change within authorised systems. Requires minimum ‘verified’ authority.
transact	Execution of a commercial or contractual transaction. Requires minimum ‘verified’ authority and explicit consent as defined in the applicable AMANAH™ policy.
notify	Issuance of a communication to defined recipients: alert, update, or disclosure.
file	Submission of a formal document to a regulatory, institutional, or legal authority. Requires minimum ‘institutional’ authority.
update	Modification of the entity’s own SHAMIL™ node. Self-referential write action. Requires minimum ‘verified’ authority. Operational enforcement requires AMANAH™ deployment.

9.3 Authority Level Registry

The following values constitute the normative Authority Level Registry for Version 1.0. M declarations must use one of these values in the authority field.

Level	Definition
public	The capability may be activated by any party without credential verification. Applies to read and non-consequential operations only.
verified	Activation requires a VSP-verified identity. Applicable to transact, notify, and write operations.
institutional	Activation requires an institutional VSP credential — a verified organisation with declared regulatory standing.
sovereign	Activation requires a sovereign or regulatory authority holding the highest VSP credential tier.

9.4 Extension Registry

Sector extensions to the SHAMIL™ standard are registered through the SHAMIL Foundation. Initial registry administration is provided by the Search Sciences™ Research Programme at Younis Group Ltd. A registered extension must define: its context URI, its additional vocabulary terms, any additional action types it introduces, and its conformance rules. Unregistered extensions are not conformant with this specification. The extension registry is maintained at:

https://shamil.foundation/extensions

Fix applied — Extension registry governance: Registry stewardship now correctly attributed to SHAMIL Foundation.Earlier drafts stated extensions are registered ‘through the Search Sciences Research Programme at Younis Group Ltd’. The SHAMIL Foundation stewards the standard and therefore maintains the extension registry. The Search Sciences Research Programme provides initial administration. This version corrects the attribution to reflect this governance structure.

10. Extension Architecture

SHAMIL™ v1.0 Core is vocabulary-agnostic. The extension architecture allows vocabulary plugins to be layered on top of the core standard without modifying it. An extension is an additional JSON-LD context referenced alongside the core context in an array.

10.1 The Schema.org Extension

The Schema.org Extension is published separately as a companion to this specification. When active, the entity file’s @context becomes an array. The Schema.org Extension adds the “schema”: “https://schema.org/” namespace, maps common SHAMIL™ attribute keys to Schema.org predicates, and promotes Schema.org properties to root level for search engine compatibility. The core standard is unchanged.

“@context”: [

“https://shamil.foundation/shamil.jsonld”,

“https://shamil.foundation/extensions/schema-org/shamil.jsonld”

]

10.2 Sector Extensions

Sector	Extension URI (planned for v2.0)
Life Sciences / Genomics	https://shamil.foundation/extensions/genomics/shamil.jsonld
Clinical / Healthcare	https://shamil.foundation/extensions/clinical/shamil.jsonld
Financial	https://shamil.foundation/extensions/financial/shamil.jsonld
Legal	https://shamil.foundation/extensions/legal/shamil.jsonld
Consumer Products	https://shamil.foundation/extensions/consumer/shamil.jsonld

11. Specification Clarifications

This section records the technical corrections and clarifications incorporated into Version 1.0 following review. It is retained as a permanent record for implementers. Items marked with an asterisk (*) are new corrections in this revision.

Correction 1: @type consistency
Earlier drafts used “@type”: “shamil:Entity” in entity file examples while simultaneously defining “Entity”: “shamil:Entity” in the context. This is inconsistent. The context alias exists precisely so that entity authors write Entity, not the namespace-prefixed form. Corrected throughout: all entity files use “@type”: “Entity”. Conformance rule C10 enforces this.

Correction 2: Interaction term mapping (most important)
Earlier drafts used “type” and “target” as plain keys inside I objects, but did not map these terms in the context file. A JSON-LD processor encountering unmapped type and target keys treats their values as plain strings, not graph edges. No RDF object properties would have been generated. Corrected: the context now maps interactionType and target. The target term carries “@type”: “@id” so that processors treat its value as an IRI reference and generate a graph edge. All entity file examples updated to use interactionType instead of type inside I objects.

Clarification 3: Attribute container semantics
The A component in the base context is a container object (shamil:Attribute) whose key-value pairs are properties of the Attribute node (typically a blank node), not direct RDF subject-predicate-object triples. This is now explicitly stated in Section 2.3 and in the conversion table at Section 8.1. The blank-node query implication is documented in the Section 2.3 design note. Vocabulary extensions may promote specific A keys to direct RDF predicates in their extended context.

Clarification 4: BNF to JSON-LD relationship
Section 3 now explicitly states: ‘In JSON-LD serialisation, AttributeDecl entries are grouped inside the A object as key-value pairs; the BNF models the authored notation form prior to serialisation.’

Clarification 5: Versioned context URI
A versioned context URI (https://shamil.foundation/context/1.0/shamil.jsonld) is now defined alongside the unversioned latest pointer. Section 4 and conformance rule C4 both reference both URIs.

Clarification 6: Interaction target validation
Conformance rule C8 now specifies that ‘resolvable’ means returning HTTP 200 or 303 at time of validation, or being a registered entity identifier within the deployment graph, or being valid under a non-HTTP identifier scheme. Graph-internal references not yet deployed are explicitly exempted.

Clarification 7: Abstract wording
The abstract previously stated entity files are ‘immediately readable by any AI system’. This overstates capability. Corrected to: ‘readable by systems capable of processing JSON-LD structured data.’

Clarification 8: Trademark and governance relationship
Section 12 includes the clarifying sentence: the SHAMIL™ trademark is owned by Younis Group Ltd and licensed to the SHAMIL Foundation for stewardship of the standard.

Addition 9: Registries
Section 9 formally defines three registries: the Action Type Registry (9.2), the Authority Level Registry (9.3), and the Extension Registry (9.4). Conformance rules C9 now reference these registries by section number.

* Correction 10: S mapping corrected
Section 2.1 previously stated ‘S maps to: rdf:subject · JSON-LD @id’. This is incorrect. S maps to shamil:Subject (the human-readable label). The canonical identifier is carried in @id, which is a separate field. The grammar table in Section 2 has been updated. Section 2.1 and Section 8.1 have been corrected. Section 4.1 context comment updated.

* Correction 11: Section 2.5 field name consistency
Section 2.5 narrative referred to the mandatory I fields as ‘type and target’. The correct field name is ‘interactionType’. Using ‘type’ would produce an unmapped JSON-LD key. Section 2.5 now uses ‘interactionType’ consistently throughout.

* Correction 12: DateRange and Unit defined in BNF
The BNF grammar in Section 3 referenced DateRange and Unit without defining them. DateRange is now defined as ISO8601Date ‘/’ ISO8601Date (ISO 8601 interval notation). Unit is defined as ‘[‘ UnitString ‘]’ — a free-text annotation on attribute values. Both definitions are added to Section 3 with accompanying notes.

* Correction 13: Method sub-terms mapped in context
The fields ‘name’ and ‘type’ inside M declaration objects were used in all examples but were not mapped in the context file. This version adds “name”: { “@id”: “shamil:methodName” } and “type”: { “@id”: “shamil:actionType” } to the context. Both IRIs are added to the Vocabulary IRI table in Section 4.3.

* Correction 14: Extension registry governance
Section 9.4 previously attributed extension registration to the Search Sciences Research Programme at Younis Group. The SHAMIL Foundation stewards the standard and therefore owns the extension registry. Corrected to: ‘The SHAMIL Foundation maintains the extension registry. Initial registry administration is provided by the Search Sciences Research Programme.’

* Clarification 15: AMANAH™ dependency documented
Section 2.4 and Section 9.2 now include explicit notes that M declarations are valid structured metadata in the absence of an AMANAH™ deployment, but that capability enforcement — and in particular the update action type — requires AMANAH™. A forward reference to the AMANAH™ companion document is included.

* Clarification 16: Reified interaction model documented
Section 2.5 now includes an explicit design note explaining the reified interaction model, its trade-offs, and the query pattern required to traverse reified relationships in SPARQL. Vocabulary extensions that promote interactionType values to direct predicates are noted as the resolution path for deployments requiring direct-triple behaviour.

* Clarification 17: Blank node query impact documented
Section 2.3 now includes an explicit design note on the blank node representation of the Attribute container and its implications for SPARQL query authors. This was previously unstated.

12. Licensing and Attribution

The SHAMIL™ specification is released under Creative Commons Attribution 4.0 International (CC BY 4.0).

Requirement	Detail
Attribution	Attribution must be given to the SHAMIL Foundation and Younis Group as originators of the standard.
TM notice	SHAMIL™ is a trademark of Younis Group Ltd, licensed to the SHAMIL Foundation for stewardship of the standard. The trademark notice must be retained in any redistribution.

Licence text: https://creativecommons.org/licenses/by/4.0/

12.1 Attribution

The SHAMIL™ notation was developed within the Search Sciences™ research programme at Younis Group by Mohammed Younis, Chief Scientist. SHAMIL™ is maintained as an open standard by the SHAMIL Foundation, an independent standards body. The trademark SHAMIL™ is owned by Younis Group Ltd and licensed to the SHAMIL Foundation for stewardship of the standard. These are distinct governance structures: Younis Group governs the intellectual programme; the SHAMIL Foundation governs the open standard.

Suggested citationYounis, M. (2026) SHAMIL™: A Structured Notation Standard for Knowledge Graph Entity Representation. Version 1.0. Search Sciences™ Research Programme. Younis Group Ltd. shamil.foundation/specifications/shamil/1.0

SHAMIL FOUNDATIONOpen Knowledge Standards