IPTC Photo Metadata Technical Reference Documentation

IPTC Photo Metadata Technical Reference Documentation
IPTC Photo Metadata Technical Reference Documentation
IPTC Photo Metadata Working Group
office@iptc.org
version 1.2,
2021-10-24
Table of Contents
About the Documentation
Acknowledgments
IPTC Photo Metadata Technical Reference Documentation History
About the IPTC Photo Metadata Technical Reference
The iptc-pmd-techreference files
IPTC Photo Metadata Technical Reference data
Terminology Used In This Document
Top Level Properties
TechReference top level property data
ipmd_top
data
ipmd_struct
data
ipmd_* data example
et_*
data
et_* data example
References
Related standards
Related tools
Fixed Errata
List of fixed errata
About the Documentation
Copyright © 2021 by IPTC, the International Press Telecommunications Council -
. 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
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
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:
as
Standard version 2021.1
Standard version 2019.1
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:
. 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
admin:
Administrative Details topic
gimgcont:
General Image Content topic
imgreg:
Image Region topic
licensing:
Licensing Use topic
location:
Location topic
othings:
Other Things Shown topic
person:
Persons Shown topic
rights:
Rights Information topic
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:
→→ 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:
→→ 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
→→ ipmdid: copyrightNotice
CopyrightNotice
→→ ipmdid: copyrightNotice
Rights
→→ ipmdid: copyrightNotice
et_instructure
CiAdrExtadr
→→ ipmdid: address
CiAdrCity
→→ ipmdid: city
CiAdrCtry
→→ ipmdid: country
CiEmailWork
→→ ipmdid: emailwork
References
Related standards
Name
Source
IPTC Photo Metadata Standard
IPTC standard covering a rich set of metadata properties for a use with images, see
. 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
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
. Document "CIPA DC-008-Translation 2019 …​ Exif Version 2.32" is used for this mapping.
IPTC IIM
IPTC Information Interchange Model:
and
ISO XMP
XMP Part 1 as ISO standard 16684-1. Latest version: Second Edition of 2019-04
PLUS
Picture Licensing Universal System – PLUS:
PLUS specifications:
Metadata Working Group
Guidelines for Handling Image Metadata v 2.0. This document was available at this URL until October 2018:
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:
Reference:
Related tools
Name
About the tool
Get IPTC PMD
Website for making visible IPTC metadata embedded into an image file, available at
(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
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
. 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