p:set-properties (3.1) 

Sets or changes document-properties.

Summary

<p:declare-step type="p:set-properties">
  <input port="source" primary="true" content-types="any" sequence="false"/>
  <output port="result" primary="true" content-types="any" sequence="false"/>
  <option name="properties" as="map(xs:QName,item()*)" required="true"/>
  <option name="merge" as="xs:boolean" required="false" select="true()"/>
</p:declare-step>

The p:set-properties step sets or changes document-properties of the source document.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

any

false

The document to adjust the document-properties of.

result

output

true

any

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

properties

map(xs:QName,item()*)

true

 

A map containing the document-properties to adjust. The keys are the document-property names, the values their values.

merge

xs:boolean

false

true

If true (default), the supplied properties in the properties option are merged with the existing document-properties, replacing/overwriting existing ones. If false, the existing document-properties are replaced.

Description

A document flowing through an XProc pipeline carries a set of document-properties with it. Document-properties are key/value pairs, where the key is a QName (which, in most cases, you can treat as just a string). Their values can be anything. Getting the value(s) of document-properties can be done using the XProc functions p:document-properties() and p:document-property().

XProc reserves three document-property names for its own usage: content-type, base-uri and serialization (see here for more information). However, you can also add your own and use them in any way you like.

The p:set-properties step can be used to change (most) document-properties. For an example of using p:set-properties see Converting XML to text in step p:cast-content-type.

Additional details

  • The p:set-properties step can not change a document media type by altering the content-type document-property. Any attempt to do this will result in error XC0069. To change a document media type use p:cast-content-type.

  • The value of the serialization document-property must be a map of type map(xs:QName, item()*). If not error XD0070 is raised.

  • Setting a document-property called base-uri changes the document’s base URI accordingly. See also category Base URI related.

Errors raised

Error code

Description

XC0069

It is a dynamic error if the properties map contains a key equal to the string “content-type”.

XD0064

It is a dynamic error if the base URI is not both absolute and valid according to RFC 3986 .

XD0070

It is a dynamic error if a value is assigned to the serialization document property that cannot be converted into map(xs:QName, item()*) according to the rules in section “QName handling” of XProc 3.0 .

Reference information

This description of the p:set-properties step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:set-properties step can be found here.

The p:set-properties step is part of categories:

The p:set-properties step is also present in version: 3.0.