About the Documentation

Copyright © 2021 by IPTC, the International Press Telecommunications Council - https://iptc.org. Rights Reserved.

The IPTC Photo Metadata Technical Reference Documentation is published under the Creative Commons Attribution 4.0 license - see the full license agreement at http://creativecommons.org/licenses/by/4.0/. By obtaining, using and/or copying this document, you (the licensee) agree that you have read, understood, and will comply with the terms and conditions of the license.

This project intends to use materials that are either in the public domain or are available by the permission for their respective copyright holders. All materials of this IPTC standard covered by copyright shall be licensable at no charge.

Acknowledgments

This document is the result of a team effort by members of Photo Metadata Working Group. The development of the TechReference is lead by Michael Steidl and these persons contributed (ordered by surname):

Brendan Quinn (IPTC), David Riecks (PLUS)

IPTC Photo Metadata Technical Reference Documentation History

The rows below keep track of versions of this documentation and not of releases of the IPTC Photo Metadata Technical Reference data file(s).

Version Release Date Release Status

1.1

2021-07-15

Initial public release

1.2

2021-10-24

IPTC Photo Metadata Standard 2021.1 incorporated

About the IPTC Photo Metadata Technical Reference

The IPTC Photo Metadata Technical Reference (TechReference) provides data reflecting the specifications of the IPTC Photo Metadata Standard in a machine-readable way and it is publicly available from IPTC in JSON or YAML format.

While the specification document of the IPTC Photo Metadata Standard defines each property with details in a format for human readers the TechReference data provides these specifications in a format which can be read by software. The TechReference data can be used by anybody for software dealing with IPTC Photo Metadata to have a stable and reliable reference of all the photo metadata properties defined by the standard. Which details about a property are provided is documented in the IPTC Photo Metadata Technical Reference data section.

This documentation of the TechReference data helps to interpret and use the data correctly.

Key features of the IPTC Photo Metadata Technical Reference data

  • Provides the specifications of all metadata properties defined by the IPTC Photo Metadata Standard in a machine-readable format.

  • Available formats: JSON and YAML.

  • The TechReference is publicly available and can be used for free …​

  • …​ if the applied http://creativecommons.org/licenses/by/4.0/ is accepted.

A mild limitation

The TechReference data provides some details in a generic way covering the slightly different specification details of data types of the XMP and the IPTC IIM format. E.g. the TechReference data name a data type "string" while XMP names it "Text" and IIM names it "sequence of octets". Therefore the proper implementation of reading and writing XMP or IIM data in a software requires to follow the format-specific specifications, they can be found in the IPTC Photo Metadata Standard document in the XMP Spec and IIM Spec rows of the specification table for each metadata property. Technical details of the XMP and IIM standards can be found in their specification documents.

The iptc-pmd-techreference files

IPTC provides the TechReference data in files of two formats.

The basic file name is iptc-pmd-techreference
The version of the IPTC Photo Metadata Standard covered by the data of a file is appended to it. For the current version of the standard 2021.1 the basic file name is iptc-pmd-techreference_2021.1

To cover additional details or to correct errors updated releases of a file may be published. The file name does not change in this case, but each file has a document_timestamp property at its top and the timestamp reflects the date and time of the release - updated releases have a newer timestamp than previous ones.

Serialization formats: JSON and YAML

To support different software environments the data of the TechReference are serialized in two formats:

  • in JSON. Full file name of this variant: e.g. iptc-pmd-techreference_2021.1.json

  • in YAML. Full filename of this variant: e.g. iptc-pmd-techreference_2021.1.yml

These files can be downloaded from this folder of the standards branch of the IPTC website: https://iptc.org/std/photometadata/specification as

IPTC Photo Metadata Technical Reference data

The IPTC Photo Metadata Technical Reference - short name: TechReference - provides data reflecting the specifications of the IPTC Photo Metadata Standard in a machine-readable format.

The TechReference uses the data model of key/value-pairs organized in hierarchical data structures, i.e. the value of a pair may hold a data structure with one to many key/value-pairs and they are understood to reside at a lower hierachical level than the key/value-pair holding this structure.

Terminology Used In This Document

  • property: A single object in a structure, in the TechReference it is a key/value-pair. It has a unique identifier (as key) and a value.

  • TechReference property: A property used by the TechReference data.

  • identifier: A string or numeric value to identify a property unambiguously in a specific scope.

  • value: The value of a property, of a key/value-pair. It can be a plain value (string, number) or a data structure making it a sub-structure of the property holding this value.

  • structure: A list of properties.

  • sub-structure: A structure being the value of a property.

  • top level property: A property of the structure at the top level of a hierarchical data model.

  • metadata property: A property defined by a metadata standard, e.g. IPTC Photo Metadata, Exif, PLUS, Dublin Core, …​ . In most cases its specification is more complex than a key/value pair, including an identifier, a semantic definition, a data type, a user interface label, etc.

  • IPTC PMD property: A metadata property defined by the IPTC Photo Metadata Standard.

  • IPTC PMD structure: A structure of metadata properties as defined by the IPTC Photo Metadata Standard.

Top Level Properties

The specifications provided by the TechReference data are grouped by top level properties.
These top level properties are used by the TechReference:

Covering the IPTC Photo Metadata Standard:

  • ipmd_top: Group of the top level metadata properties of the IPTC Photo Metadata Standard. They are listed in the Metadata Properties sections of the IPTC Core schema and IPTC Extension schema chapters of the Standard’s specification document.

  • iptc_struct: Group of metadata structures of the IPTC Photo Metadata Standard. They are listed in the Metadata Structures sections of the IPTC Core schema and IPTC Extension schema chapters of the Standard’s specification document.

Covering Tags of the software ExifTools

The software ExifTool supports all properties of the IPTC Photo Metadata Standard. IPTC suggests to use it for reading and writing photo metadata.

ExifTool identifies metadata properties by a Tag. Such a Tag has a Tag ID as identifer related to the property of a photo metadata standard. Each Tag resides in a tag group defined by ExifTool typically reflecting the standard the metadata property belongs to, e.g. "XMP" stands for the XMP format, "IPTC" stands for the IIM format. The identifier of such a tag group may be used as prefix of an ExifTool Tag using the format {tag-group identifier}:{ExifTool Tag ID}

  • et_topwithprefix: Group of ExifTool Tags with a prefix expressing the tag group it belongs to. Each ExifTool Tag corresponds to one of the top level properties of the IPTC Photo Metadata Standard and the properties of the ipmd_top group, see above.

  • et_topnoprefix: Group of the same ExifTool Tags as in et_topwithprefix, but having no prefix.

  • et_instructure: Group of ExifTool Tags corresponding to a metadata property in a structure defined by the IPTC Photo Metadata Standard. They are listed in the Metadata Structures sections of the IPTC Core schema and IPTC Extension schema chapters of the Standard specification document.

TechReference top level property data

Find below a list of all the data provided by each of the top level properties of the TechReference data.

ipmd_top data

The structure of the ipmd_top TechReference property has a property for each top level metadata property specified by the IPTC Photo Metadata Standard, more than 55 currently. Such a TechReference property has an identifier (key) and a structure as value; what it defines is the same as the human-readable specification table of the corresponding top level property in the IPTC Photo Metadata Standard specification document. See the specification table template explaining what each of its rows define.
Find the details below.

  • identifier: Short alphanumeric string without whitespace. It is the same identifier as defined in the JSON Specs row in the specification table of this IPTC PMD property in the Standard’s specification document.

  • value’s structure: This structure supports all the properties listed below.

    • name: Text naming the IPTC PMD property, taken from the Property Name row of the specification table of this property in the Standard’s specification document. Expect name for all IPTC PMD properties.

    • ipmdschema: The used values "IptcCore" and "IptcExtension" refer to the two schemas (= vocabularies) of the IPTC Photo Metadata Standard. Each IPTC photo metadata property is a member of one of these two schemas. Expect ipmdschema for all IPTC PMD properties.

    • sortorder: A short alphanumeric string supporting a lexical sort order of IPTC Photo Metadata property names across the schemas IPTC Core and IPTC Extension. Expect sortorder for all IPTC PMD properties.

    • ugtopic: Identifier of one of the topics grouping IPTC metadata properties in the IPTC Photo Metadata User Guide. Find the used identifiers below. Expect ugtopic for all IPTC PMD properties.

    • specidx: Fragment of a URL starting with "#" and targeting the specification table of the corresponding IPTC PMD property in the IPTC Photo Metadata Standard web document. To get a full URL this fragment must be appended to this base URL: https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata. Expect specidx for all IPTC PMD properties.

    • datatype: Defines the data type of the value of the IPTC PMD property. Used data types: string, number, struct. If struct is used the structure used by the IPTC PMD property value is defined by dataformat. Expect datatype for all IPTC PMD properties.

    • dataformat: Defines a specific data format of the value of the IPTC PMD property if required. Used dataformats are: i/ with data type string: date-time, uri, url; ii/ with data type number: integer. If the data type is struct dataformat holds the identifier of the assigned IPTC PMD structure, these structures and their idenfiers can be found in the structure of the ipmd_struct top level property of the TechReference. Expect dataformat for all IPTC PMD properties with struct as data type.

    • propoccurrence: Defines how many times the IPTC PMD property may occur: single: not at all or one time, multi: not at all or multiple times. Expect propoccurrence for all IPTC PMD properties.

    • isrequired: Defines if this IPTC PMD property should be considered as semantically required when processing IPTC Photo Metadata. As the IPTC Photo Metadata Standard does not define any semantic requirement the value of this property is set to "0" in the TechReference. But for a personalized use of the TechReference isrequired can bet set to e.g. "1" for indicating to a metadata processor "this property must exist in our metadata".

    • XMPid: Identifier of the XMP property as defined by the IPTC PMD property. The XMP property identifier may appear in an XMP packet using the format namespace prefix:local identifier. Expect XMPid for all IPTC PMD properties.

    • IIMid: Identifier of the IPTC IIM Data Set (same as a property) as defined by the IPTC PMD property. The IIM Data Set identifier may appear in a block of IPTC IIM data using the format record number:data set number. Expect IIMid only for IPTC PMD properties defining an IIM Data Set.

    • IIMname: Name of the IPTC IIM Data Set of IIMid.

    • IIMmaxbytes: Integer value defining the maximum count of bytes which can be used with the IIM Data Set of IIMid. Be aware: non-ASCII characters in UTF-8 may use more than 1 byte per character. Expect IIMmaxbytes only for IPTC PMD properties with a datatype of string.

    • EXIFid: Numeric identifier (tag) of an Exif property mapped to the IPTC PMD property. The numeric value is expressed using the decimal numeral system. Expect EXIFid only for IPTC PMD properties being mapped to an Exif Tag.

    • SCHEMAid: Identifier of a Schema.org metadata property mapped to the IPTC PMD property. The data type of the value is URL. Expect SCHEMAid only for IPTC PMD properties being mapped to a Schema.org property.

    • etXMP: ExifTool tag identifing the XMP property (see above: XMPid) of the IPTC PMD property. Expect etXMP for all IPTC PMD properties.

    • etIIM: ExifTool tag identifing the IIM data set (see above: IIMid) of the IPTC PMD property. Expect etIIM only for IPTC PMD properties with an IIMid.

    • etEXIF: ExifTool tag identifing the Exif property (see above: EXIFid) mapped to the IPTC PMD property. Expect etIIM only for IPTC PMD properties with an EXIFid.

    • etTag: ExifTool tag identifing a property without an explicitly related standard. Used only for a few ExifTool tags like the version tag covering the used ExifTool software.

ugtopic values

These values are used for the ugtopic TechReference property referring to a topic in the IPTC Photo Metadata User Guide:

ipmd_struct data

The structure provided by the ipmd_struct property has a property for each metadata structure specified by the IPTC Photo Metadata Standard, more than 15 currently. Such a TechReference property has an identifier (key) and a structure as value. Find the details below.

  • identifier: Short alphanumeric string identifing the IPTC PMD structure; without whitespace, typically starting with uppercase. It is the same identifier as defined in the JSON Specs row in the specification table of this IPTC PMD structure in the Standard’s specification document.

  • value structure: the TechReference property representing a metadata structure has as value a sub-structure for the IPTC metadata properties defined for this IPTC PMD structure. Each of the properties has an identifier (key) and a structured value.

    • identifier: short alphanumeric string identifing the IPTC PMD property inside the IPTC PMD structure; without any whitespace. It is the same as the identifier defined in JSON Specs row of the specification table of this property inside a structure in the IPTC Photo Metadata Standard.

    • value structure: The structure supports all the properties listed below.

      • name: same as for ipmd_top, see above.

      • ipmdschema: same as for ipmd_top, see above.

      • sortorder: same as for ipmd_top, see above.

      • specidx: same as for ipmd_top, see above.

      • datatype: same as for ipmd_top, see above.

      • dataformat: same as for ipmd_top, see above.

      • propoccurrence: same as for ipmd_top, see above.

      • isrequired: same as for ipmd_top, see above.

      • XMPid: same as for ipmd_top, see above.

      • EXIFid: same as for ipmd_top, see above.

      • SCHEMAid: same as for ipmd_top, see above.

      • etXMP: same as for ipmd_top, see above.

      • etTag: same as for ipmd_top, see above.

Special case AltLang structure

The structure identified by AltLang is different from all other structures. It covers the special feature of XMP metadata to provide semantically the same text value in alternative, different languages. To cover this feature an IPTC PMD property value of the type struct with the dataformat AltLang should be treated as a data structure with keys conforming to language identifiers as defined by BCP 47. XMP specifies the special key x-default to indicate "the used language is the default language of the metadata", in fact this key is the most widely used in practice.

ipmd_* data example

The hierarchical levels of the TechReference properties are made visible by → arrows.
The keys of the top level ipmd_…​ TechReference properties are in bold.
The identifier of an IPTC PMD property or structure is shown in italics.
All other property keys follow the definition in the previous sections, the values are taken from a recent release of the TechReference data using the YAML format.
Comments are in {}-brackets, they do not appear in the TechReference file.
The IPTC PMD property examples cover one with an Alternate Language value, one with plain string value, and one with a structured value.

ipmd_top:
→ copyrightNotice: {identifier of IPTC PMD property}
→→ name: Copyright Notice
→→ ipmdschema: IptcCore
→→ sortorder: tp150
→→ ugtopic: rights
→→ specidx: '#copyright-notice'
→→ datatype: struct
→→ dataformat: AltLang
→→ propoccurrence: single
→→ isrequired: '0'
→→ IIMid: 2:116
→→ IIMname: Copyright Notice
→→ IIMmaxbytes: 128
→→ XMPid: dc:rights
→→ EXIFid: '33432'
→→ SCHEMAid: https://schema.org/copyrightNotice
→→ etXMP: XMP-dc:Rights
→→ etIIM: IPTC:CopyrightNotice
→→ etEXIF: IFD0:Copyright
→ creditLine: {identifier of IPTC metadata property}
→→ name: Credit Line
→→ ipmdschema: IptcCore
→→ sortorder: tp230
→→ ugtopic: rights
→→ specidx: '#credit-line'
→→ datatype: string
→→ propoccurrence: single
→→ isrequired: '0'
→→ IIMid: 2:110
→→ IIMname: Credit
→→ IIMmaxbytes: 32
→→ XMPid: photoshop:Credit
→→ SCHEMAid: https://schema.org/creditText
→→ etXMP: XMP-photoshop:Credit
→→ etIIM: IPTC:Credit
→ imageCreators: {identifier of IPTC PMD property}
→→ name: Image Creator
→→ ipmdschema: IptcExt
→→ sortorder: tp350
→→ ugtopic: rights
→→ specidx: '#image-creator'
→→ datatype: struct
→→ dataformat: ImageCreator {see the structure with this identifer in the ipmd_struct region below}
→→ propoccurrence: multi
→→ isrequired: '0'
→→ XMPid: plus:ImageCreator
→→ etXMP: XMP-plus:ImageCreator
ipmd_struct:
→ ImageCreator: {identifier of IPTC PMD structure}
→→ imageCreatorId: {identifier of IPTC PMD property in the structure}
→→→ name: Image Creator ID
→→→ ipmdschema: PLUS
→→→ sortorder: s3301
→→→ specidx: '#image-creator-id'
→→→ datatype: string
→→→ propoccurrence: single
→→→ isrequired: '0'
→→→ XMPid: plus:ImageCreatorID
→→→ etTag: ImageCreatorID
→→ imageCreatorName: {identifier of a metadata property in the structure}
→→→ name: Image Creator Name
→→→ ipmdschema: PLUS
→→→ sortorder: s3302
→→→ specidx: '#image-creator-name'
→→→ datatype: string
→→→ propoccurrence: single
→→→ isrequired: '0'
→→→ XMPid: plus:ImageCreatorName
→→→ EXIFid: '315'
→→→ etTag: ImageCreatorName
→→→ etEXIF: IFD0:Artist

et_* data

The TechReference top level properties et_topwithprefix, et_topnoprefix and et_instructure provide a structure of ExifTool Tag properties. Each of the ExifTool Tag properties provides a structure with a single property. See a generic overview below:

  • et_topwithprefix or et_topnoprefix or et_instructure

    • ExifTool Tag: Identifier of an ExifTool property using a different naming in each of the top level properties (see below)

    • ExifTool property value’s structure: It supports the property shown below.

      • ipmdid: TechReference-identifier of the corresponding IPTC Photo Metadata property. This must be an identifier of an IPTC PMD property at the top level (ipmd_top) or in a structure (ipmd_struct).

ExifTool top level properties and their naming of tags:

ExifTool identifies metadata properties by a Tag. Such a Tag has a Tag ID as identifer related to the property of a photo metadata standard. Each Tag resides in a tag group defined by ExifTool but reflecting the standard the metadata property belongs to, e.g. "XMP" stands for the XMP format, "IPTC" stands for the IIM format. The identifier of such a tag group may be used as prefix of an ExifTool Tag using the format {tag-group identifier}:{ExifTool Tag ID}.

The prefix used in the TechReference corresponds to prefixes supported by the "-G1" command line parameter of ExifTool named as "groups in family 1" by ExifTool.
Be aware that a different family of groups defines different prefixes.
Be aware that some software modules wrapping ExifTool in JavaScript, Python or C# (and other languages) use "-G" by default, which is "groups in family 0" with prefixes different from the "groups in familiy 1" prefixes - the "-G1" parameter needs to be set explicitly in most cases.

  • et_topwithprefix: This structure provides ExifTool tags of properties corresponding to IPTC PMD properties at the top level, see ipmd_top data above.
    ExifTool tags in this structure are used with a prefix but a slightly different format: as this colon may cause syntactic problems in YAML keys IPTC decided to replace it by an underscore "_" making the format {tag-group identifier}_{ExifTool Tag ID}. This format is only used for the ExifTool Tag in the et_topwithprefix structure. Find ExifTool Tags with an underscore in the et_* data example below.

  • et_topnoprefix: This structure provides the same ExifTool tags as in the et_topwithprefix structure but without a prefix.

  • et_instructure: This structure provides ExifTool tags of properties corresponding to IPTC PMD properties in an IPTC PMD structure, see ipmd_struct data above.
    ExifTool tags in this structure are used without a prefix.

et_* data example

The hierarchy levels of the TechReference properties are made visible by → arrows.
The keys of the top level et_…​ TechReference properties are in bold.
The ExifTool Tag of a metadata property shown in italics.
All other property keys follow the definition in the previous section, the values are taken from a recent release of the TechReference using the YAML format.

et_topwithprefix:
→ IPTC_City:
→→ ipmdid: cityName
→ XMP-photoshop_City:
→→ ipmdid: cityName
→ IFD0_Copyright:
→→ ipmdid: copyrightNotice
→ IPTC_CopyrightNotice:
→→ ipmdid: copyrightNotice
→ XMP-dc_Rights:
→→ ipmdid: copyrightNotice
et_topnoprefix:
→ City:
→→ ipmdid: cityName
→ Copyright:
→→ ipmdid: copyrightNotice
→ CopyrightNotice:
→→ ipmdid: copyrightNotice
→ Rights:
→→ ipmdid: copyrightNotice
et_instructure:
→ CiAdrExtadr:
→→ ipmdid: address
→ CiAdrCity:
→→ ipmdid: city
→ CiAdrCtry:
→→ ipmdid: country
→ CiEmailWork:
→→ ipmdid: emailwork

References

Name Source

IPTC Photo Metadata Standard

IPTC standard covering a rich set of metadata properties for a use with images, see https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata. It also defines how the properties can be embedded into image files using the XMP format (Adobe XMP, ISO XMP) or the IPTC IIM format.

Adobe XMP

Adobe Extensible Metadata Platform (XMP), see http://www.adobe.com/products/xmp/
Latest specification as of August 2016
These documents include the specification of the metadata schemas Dublin Core, XMP Rights management and Photoshop which are referenced in this specification.

Exif

Exchangeable Image file Format (Exif), published by Camera & Imaging Products Association (Japan). See all CIPA documents at https://www.cipa.jp/std/std-sec_e.html. Document "CIPA DC-008-Translation 2019 …​ Exif Version 2.32" is used for this mapping.

IPTC IIM

IPTC Information Interchange Model: http://www.iptc.org/IIM/ and http://www.iptc.org/std/IIM/4.2/specification/IIMV4.2.pdf

ISO XMP

XMP Part 1 as ISO standard 16684-1. Latest version: Second Edition of 2019-04

PLUS

Picture Licensing Universal System – PLUS: http://www.useplus.org
PLUS specifications: http://www.useplus.com/useplus/standards.asp

Metadata Working Group

Guidelines for Handling Image Metadata v 2.0. This document was available at this URL until October 2018: http://www.metadataworkinggroup.com/specs/

Schema.org Vocabulary

Schema.org is a collaborative, community activity behind a vocabulary for structured data on the Internet. See the overview of schemas provided by this community.

W3C-SKOS

SKOS Simple Knowledge Organization System
Overview: http://www.w3.org/2004/02/skos/
Reference: http://www.w3.org/TR/skos-reference/
Name About the tool

Get IPTC PMD

Website for making visible IPTC metadata embedded into an image file, available at https://getpmd.iptc.org (it is run by IPTC). The process of matching found properties against the IPTC standard is based on the IPTC Photo Metadata Technical Reference.

ExifTool

Software for reading and writing photo metadata from and into an image file. Available as Perl library (can be installed on a Linux computer) or command line tool for Windows and MacOS. All about in at https://exiftool.org/
As ExifTool supports all properties defined by the IPTC Photo Metadata standard IPTC suggests to use it.

IPTC Photo Metadata User Guide

A document providing guidelines for a proper use of the IPTC Photo Metadata Standard, see https://www.iptc.org/std/photometadata/documentation/userguide/. The IPTC metadata properties are grouped by these topics: General Image Content, Persons Shown, Locations, Other Things Shown, Rights Information, Licensing Use, Administration Details, Image Region. Identifiers of these topics are used by the TechReference.

Fixed Errata

List of errata in the IPTC Photo Metadata Technical Reference Documentation which were fixed after the initial release of version 1.0

List of fixed errata

Date Error How the error was fixed