Smart Scholars DOI Metadata Format 1.0
Our own documented metadata format, meeting the DOI Kernel of ISO 26324: one record per DOI, every Kernel element, and the mapping to the Kernel Metadata Declaration. Try it on any DOI: Kernel Metadata Declaration on demand.
Files: the specification (Markdown) · the JSON Schema · the reference implementation is includes/ssmd.php on every Smart Scholars site. Sources: the DOI Kernel XML schema (doi:10.1000/276), the DOI Attribute Value Sets 2.3 (doi:10.1000/282), the DOI Handbook (Data Model).
Version 1.0 — 29 September 2026. Format identifier smartscholars-doi-metadata/1.0. Maintained by Smart Scholars, Hyderabad, India. Reference implementation: includes/ssmd.php; machine-readable rules: docs/ssmd-1.0.schema.json; the declaration on demand: kernel.php?doi=….
1. Purpose
Every DOI name a Registration Agency issues must be describable by a DOI Kernel Metadata Declaration (ISO 26324; DOI Handbook, Data Model §4.1: "An RA must be capable of producing a Kernel Metadata Declaration for each DOI name issued"). The Handbook allows an agency to hold a wider schema of its own and to convert to the Kernel on demand (§4.3.2). This document is that wider schema: one record per DOI, holding every Kernel element and, beside them, what journals, indexes and readers need every day — the abstract, the licence, the links, the references, the funding, and where the item sits in its journal or book.
The referent "shall be described unambiguously and precisely" and "recorded promptly and accurately" (Handbook §4.4). A record that fails any rule in §4 is not accepted.
2. The record
A record is one JSON object (UTF-8). Keys are lower-case with underscores. Values that are controlled vocabularies use the DOI Attribute Value Sets (AVS) 2.3 spellings verbatim, so that a value written here is a value the Kernel accepts.
| Key | Required | Meaning |
|---|---|---|
format | yes | Always smartscholars-doi-metadata/1.0. |
doi | yes | The DOI name, lower case: 10.<prefix>/<suffix>. |
referent | yes | The Kernel primaryReferentType. Creation in 1.0 (Party records are reserved for a later version). |
type | yes | What the DOI identifies — a Kernel creationType from the list in §3: JournalArticle, Book, BookChapter, ConferenceProceedings, Dataset, Report, Thesis, Standard, Figure, WebResource, Journal, JournalIssue, JournalVolume, BookSeries. |
structural_type | yes | Kernel structuralType: Digital, Physical, Abstraction or Performance. |
modes | yes | Kernel mode(s), at least one: Visual, Audio, Tangible, Olfactory, Tasteable. |
characters | yes | Kernel character(s), at least one: Language, Image, Music, Other. |
titles | yes | A list of {value, type, lang?, subtitle?}. Exactly one title has type PrincipalTitle; others may be Title, TranslatedTitle, AbbreviatedTitle, FormerTitle, DistinctiveTitle, Name. lang is a BCP 47 tag. |
identifiers | yes | A list of {type, value, namespace?, governing_party?}; must include the record's own DOI as {type: "DOI"}. Types are Kernel creationIdentifierTypes (DOI, ISSN, ISBN13, ISBN10, PII, URI, URN, UUID, ProprietaryIdentifier, …). A ProprietaryIdentifier names its namespace (who issues it). |
agents | yes | A list of {role, name, identifiers?, affiliations?, sequence?} — at least one, because the Kernel requires a principalAgent. role is one of ours (§5): author, editor, translator, contributor, chair, corporate_author, publisher, funder. name is {given, family} or {org} or {display}. Identifiers: ORCID (0000-0000-0000-000X), ISNI, ROR (the 9-character id), DOI, ProprietaryIdentifier. Affiliations: {name, identifiers?} with ROR ids. |
dates | yes | {published, date_type?, online?, print?, accepted?, …}. published is required; every date is YYYY, YYYY-MM, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. date_type is PublicationDate (default) or ReleaseDate. |
language | no | BCP 47 tag of the content (en, hi, pt-BR). |
container | no | The journal, book, proceedings or series this creation is part of: {type, titles, identifiers, volume?, issue?, pages?: {first, last?}, article_number?}. A journal container carries its ISSN (with medium print or electronic). |
relations | no | Other creations this one is linked to: {role, of, identifiers?, titles?}. role is a Kernel creationToCreationLinkRole (IsSameAs, Version, Translation, Part, Derivation, SupplementalResource, Edition, …); of says who plays the role — referent (this record is a Version of the other) or linked (the other is a Version of this one). |
links | no | {url, return_type?, primary?, purpose?}. At most one link is primary — the landing page the DOI resolves to. return_type is a media type. |
abstract | no | {value, lang?} — plain text, no markup. |
license | no | {url, start?, applies_to?}. |
funding | no | {name, identifiers?, awards?} per funder (also listed among agents with role funder). |
references | no | {key, doi?, unstructured?} per cited work. Not part of the Kernel; kept for the Crossref crosswalk and Citation Integrity Watch. |
updates | no | {type, doi, date, label?} — the DOIs this record corrects or retracts. |
record | yes | {registrant, registered?, updated?, issue_number?, source?, source_agency?}. registrant is who registered the DOI; issue_number (from 1) is the sequence number of the Kernel Declaration issued for this DOI. |
3. Referent types and their default Kernel classification
type | structural_type | modes | characters | What it is | Crossref work types it is read from |
|---|---|---|---|---|---|
JournalArticle | Digital | Visual | Language | an article in a journal | journal-article |
Journal | Abstraction | Visual | Language | a journal as a whole (title-level DOI) | journal |
JournalIssue | Digital | Visual | Language | one issue of a journal | journal-issue |
JournalVolume | Digital | Visual | Language | one volume of a journal | journal-volume |
Book | Digital | Visual | Language | a book (monograph, edited volume) | book, monograph, edited-book, reference-book |
BookChapter | Digital | Visual | Language | a chapter or part of a book | book-chapter, book-part, book-section |
BookSeries | Abstraction | Visual | Language | a series of books | book-series, book-set |
ConferenceProceedings | Digital | Visual | Language | a conference paper or a proceedings volume | proceedings-article, proceedings |
Dataset | Digital | Visual | Other | a dataset or a database record | dataset, database |
Report | Digital | Visual | Language | a report | report, report-component |
Thesis | Digital | Visual | Language | a thesis or dissertation | dissertation |
Standard | Digital | Visual | Language | a standard | standard |
Figure | Digital | Visual | Image | a figure, table or supplementary file | component |
WebResource | Digital | Visual | Language | a web resource or posted content (preprint, blog post) | posted-content, peer-review, other |
A registrant may override structural_type, modes and characters (a printed-only book is Physical; an audio article is Audio + Language). Every value stays within the AVS lists.
4. Rules
format,doi,referent,type,structural_type,modes,characters,titles,identifiers,agents,dates.publishedandrecord.registrantare required.doimatches10.<prefix>/<suffix>and is stored lower case;identifiersinclude it as typeDOI.- Exactly one
PrincipalTitle. - Every controlled value is an AVS 2.3 spelling (§2, §3, §5). A value outside the list is refused, never mapped silently.
- An ORCID iD is written bare (
0009-0003-2056-724X), a ROR id bare (05gq02987); the Kernel export adds thehttps://orcid.org/andhttps://ror.org/addresses. - Dates are ISO 8601 at the granularity known — never a guessed day.
- A journal container carries its ISSN.
- At most one primary link.
- A record is never accepted with a placeholder title, agent or date; a Crossref record with no title is imported with the visible marker "(no title on the Crossref record)" so that it fails rule 1 of review, not silently passes.
5. Mapping to the DOI Kernel Metadata Declaration
The export writes DOIMetadataKernel.xsd (namespace http://www.doi.org/2010/DOISchema, AVS 2.3), elements in the schema's order.
| Kernel element | From the record |
|---|---|
referentDoiName | doi |
primaryReferentType | referent |
registrationAgencyDoiName | the agency's DOI name (setting ra_doi_name); until accreditation the marker 10.0/smart-scholars-draft and an XML comment saying the declaration is a draft (10.0/ is no agency's prefix — real prefixes start at 10.1000) |
issueDate | the day the declaration is produced |
issueNumber | record.issue_number (1 when unset) |
referentCreation/name | titles → creationName (value, subnameValue from subtitle, type, @primaryLanguage from lang) |
referentCreation/identifier | identifiers → creationIdentifier (nonUriValue and, for a DOI, the uri https://doi.org/… with returnType="text/html" doesContentNegotiation="true"); then every links entry as an identifier of type URI (the landing page with returnType="text/html"; a PDF carries no returnType, because the AVS returnType list is closed: application/rdf+xml, application/xml, text/html, text/xml) |
structuralType, mode, character, type | structural_type, modes, characters, type |
principalAgent | each of agents: name (partyName, type PrincipalName), one identifier (the ORCID when there is one — the schema allows one identifier per agent; a ROR id travels as ProprietaryIdentifier with its https://ror.org/ uri), role from the table below |
linkedCreation (container) | container → names, identifiers (ISSN/ISBN), referentCreationRole = Part, referentCreationSequenceIdentifiers VolumeNumber, IssueNumber, PageNumber (first–last), and an article_number as a ProprietaryIdentifier |
linkedCreation (relations) | each of relations: names, identifiers, referentCreationRole (when of = referent) or linkedCreationRole (when of = linked) |
language | the record's language (language) |
languageOfReferentContent | language, type Original (Translation when the record is a translation) |
creationDate | dates.published, creationDateType from dates.date_type |
Our agent roles map to the Kernel agentRole list (AVS 2.3 has no Editor or Translator; they are Creators of the version at hand):
| Ours | Kernel agentRole |
|---|---|
author | Author |
editor, translator, contributor, chair | Creator |
corporate_author | CorporateCreator |
publisher | Publisher |
funder | FundingBody |
Not in the Kernel and therefore not exported: abstract, license, references, updates, funding.awards, affiliations. They stay in the record for the Crossref crosswalk and the services.
6. Reading a record from Crossref
Every DOI in Smart Scholars' care today is registered through Crossref, so every one has a public work record (api.crossref.org/works/<doi>). ssmd_from_crossref() turns that work into a record: type from the work type (§3), titles (first = PrincipalTitle, subtitle, original titles), the DOI and ISBNs and alternative-ids as identifiers, authors / editors / translators / chairs with ORCID (bare) and ROR-bearing affiliations, the publisher as a publisher agent, funders as funder agents and funding, dates (published, then issued, then created; online, print, accepted when present), the container (title, abbreviated title, ISSNs with medium, volume, issue, pages, article number), relations (is-same-as, is-version-of / has-version, is-translation-of / has-translation, is-part-of / has-part, is-derived-from / has-derivation, is-supplement-to / is-supplemented-by, is-preprint-of / has-preprint), links (the primary resource URL, then each link), the abstract as plain text, the licence (version of record preferred), references and update-to. record.registrant is the publisher; record.source is crossref-api with the member number.
Every text field read from Crossref — titles, container titles, names, publisher, funders, the abstract — has its markup dropped and its character references decoded, twice: JST's deposits left Crossref holding Journal of Science & Technology in 915 of 928 records (a double escaping by the depositor), and the record holds the text that was meant. The "Compare with Crossref" page shows such a difference for what it is — the depositor's to correct at Crossref.
Two cases seen in the first registry import (29 Sep 2026): a title-level record — a work of type journal or book-series — is the serial itself, so it gets no container; its ISSN becomes one of its own identifiers. A volume or issue record that names its journal (container-title) but omits the ISSN takes the ISSN the caller knows for that title (ssmd_from_crossref($w, ['issn_by_title' => [lower-cased title => [{value, medium}]]])); the registry supplies it from the page being imported and from the records it already holds, so a journal whose ISSN no record here carries is still refused with the reason.
7. Where to see it
journals.smartscholars.in/kernel.php?doi=<doi> shows, for any DOI, the record, the rule check and the Kernel Metadata Declaration, and offers both as files (&as=json, &as=xml). It is the demonstration that a declaration can be produced on demand for each DOI (§4.3.2 of the Handbook) before the registry itself exists.
8. Sources
DOI Kernel XML schema DOIMetadataKernel.xsd (doi:10.1000/276) — https://www.doi.org/doi_schemas/DOIMetadataKernel.xsd · DOI Attribute Value Sets 2.3, 2023 (doi:10.1000/282) — https://www.doi.org/doi_schemas/DOIAVS.xsd · DOI Handbook, Data Model — https://www.doi.org/doi_handbook/4_Data_Model.html · Crossref REST API — https://api.crossref.org/swagger-ui/index.html
