HAPI FAQ: Understanding Projects API and Publication Stages

HAPI FAQ – Publications API

Where is the Publications API documented?

Common XSD : https://bitbucket.org/sdo-hapi/data-models/src/master/schema/xsd/common/harmonized-commons.xsd
XSD : https://bitbucket.org/sdo-hapi/data-models/src/master/schema/xsd/projects/harmonized-projects.xsd
OpenAPI YAML: https://bitbucket.org/sdo-hapi/api-specifications/src/master/openapi-v3/iec-projects-publications-openapi3.yaml
OpenAPI: IEC API Portal – https://api-portal.iec.ch/ (developer account required)

Why do some publications have no project?

Category	How to recognize	Example
Joint ISO/IEC standards published by ISO	`originator` = `ISO`	`iec:pub:63077` – ISO/IEC TS 22237-5:2018
Old joint standards originated by IEC, published by ISO (all revised/replaced/withdrawn)	`originator` = `IEC`, ISO reference	`iec:pub:21043` – ISO 81400-4:2005
Database standards	`releaseItem/format` = `ONLINE`	`iec:pub:2723` – IEC 60617:2012 DB
Packages	`publicationType` = `PACK`	`iec:pub:61124` – IEC 61970-CGMES:2022
Series (marketing products)	`publicationType` = `SERIES`	`iec:pub:62437` – IEC 60068-2:2022 SER
Other publications (Guides, White Papers, Trend Reports…)	`publicationType` = `PUBLICATION`	`iec:pub:79674`
Commented versions	`publicationType` = `COMMENTED`	–
Other	`stdType` = `OTHER`	–

How do I identify Database (DB) publications?

There is no dedicated publicationType for DBs. Identify them by releaseItem/format = ONLINE (no project, no downloadable file). The five DB standards are: iec:pub:474, iec:pub:980, iec:pub:2098, iec:pub:2723, iec:pub:7514.

What publication statuses exist?

Status	Meaning
`PUBLISHED`	Current and valid
`REVISED`	A new edition or amendment was published (same `stdNumber`/part/section). Still available.
`REPLACED`	Replaced by one or more standards with a different `stdNumber`/part/section or `publicationType`. Still available.
`WITHDRAWN`	No longer maintained. Still available.

dateOfWithdrawal = date the publication stopped being valid (revised, replaced or withdrawn).

What happens to projects when a publication changes status?

New edition/amendment → previous edition and all its amendments, CSV, CMV become REVISED; project stage becomes DELPUB.
Replaced by a different standard → REPLACED; project stage becomes DELPUB.
No longer maintained → WITHDRAWN; project stage becomes WPUB.

Why is "Withdrawn" different between the API and the Webstore?

The Webstore shows "Withdrawn" (in red) for any publication no longer valid, with history available. The API uses the precise IEC statuses above (REVISED / REPLACED / WITHDRAWN).

Example – IEC 61107:

Project	Stage	Publication	Reference	Status	Superseded by
`iec:proj:7145`	DELPUB	`iec:pub:19046`	IEC 61107:1992 ED1	REVISED	`iec:pub:19047`
`iec:proj:7146`	DELPUB	`iec:pub:19047`	IEC 61107:1996 ED2	REPLACED	`iec:pub:6398`
`iec:proj:9250`	PPUB	`iec:pub:6398`	IEC 62056-21:2002 ED1	PUBLISHED	–

Why does `dateOfWithdrawal` differ from the WPUB date in the Projects API?

dateOfWithdrawal (Publications API, Webstore) = actual withdrawal date.
effectiveDate of stage WPUB (Projects API) = announcement date of the withdrawal.

Why are relations missing on corrigenda of consolidated versions?

A corrigendum can correct a consolidated version (e.g. IEC 60529:1989+AMD1:1999 CSV/COR1:2003). Consolidated versions have no own project (they link to the base project), and the Publications API has no publication-to-publication relations. CORRECTS/CORRECTED_BY cannot be provided today. This is a known limitation.

Which languages are available?

Language	`contentLanguage`	`multilingual`
EN-FR	`["en","fr"]`	true
EN	`["en"]`	false
ES	`["es"]`	false
FR	`["fr"]`	false
RU	`["ru"]`	false

Publication languages can differ from the project's languageSettings (e.g. a project developed in English, translated later: iec:proj:8383 / iec:pub:5972).

Why do downloads fail for some language versions?

Language versions other than English and French require a contract with IEC Sales. Exception: trilingual EN/FR/RU publications.