# Smart Scholars DOI Metadata Format 1.0

*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 `creationIdentifierType`s (`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

1. `format`, `doi`, `referent`, `type`, `structural_type`, `modes`, `characters`, `titles`, `identifiers`, `agents`, `dates.published` and `record.registrant` are required.
2. `doi` matches `10.<prefix>/<suffix>` and is stored lower case; `identifiers` include it as type `DOI`.
3. Exactly one `PrincipalTitle`.
4. Every controlled value is an AVS 2.3 spelling (§2, §3, §5). A value outside the list is refused, never mapped silently.
5. An ORCID iD is written bare (`0009-0003-2056-724X`), a ROR id bare (`05gq02987`); the Kernel export adds the `https://orcid.org/` and `https://ror.org/` addresses.
6. Dates are ISO 8601 at the granularity known — never a guessed day.
7. A journal container carries its ISSN.
8. At most one primary link.
9. 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`, `referentCreationSequenceIdentifier`s `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-id`s 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 &amp; 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