Mapsoft TDMRep - User Guide

Overview

TDMRep stands for Text and Data Mining Reservation Protocol. It is a W3C standard that allows publishers and rights holders to embed a simple declaration inside a PDF stating whether AI systems and other automated tools are allowed to mine the document's content.

In plain terms: when an AI crawler encounters your PDF, it can read this declaration to know whether it is permitted to use your content for training or analysis — or whether it needs to contact you for a licence first.

Mapsoft TDMRep is a free Adobe Acrobat plug-in that makes it easy to set, check, and remove these declarations on individual PDFs or entire folders of documents.

What is TDMRep?

TDMRep (Text and Data Mining Reservation Protocol) is a W3C community standard that allows rights holders to express their TDM rights using two XMP metadata properties:

Property	Values	Description
`tdm:reservation`	`0` or `1`	0 = TDM rights are not reserved (mining is permitted). 1 = TDM rights are reserved (mining may require a licence).
`tdm:policy`	URL	Optional URL pointing to a machine-readable TDM policy set by the rights holder. Only meaningful when `tdm:reservation` is `1`.

The namespace URI for TDMRep is http://www.w3.org/ns/tdmrep/.

Using the Plug-in

Setting TDM Reservation on a Single Document

Open a PDF document in Adobe Acrobat.
Go to Extensions > TDM Reservation > TDM Reservation...
The dialog shows the current TDMRep status of the document (if any).
Select a Reservation value:
- 0 – TDM rights not reserved (mining permitted)
- 1 – TDM rights reserved
If reservation is set to 1, optionally enter a Policy URL pointing to your TDM licensing policy. The URL field is optional — leave it blank if you don't have a policy yet.
Optionally click Check to test that the URL is reachable. This is informational only; you can apply the URL even if the check fails (for example, if the policy is not deployed yet).
Check Include PDF/A extension schema if you need the document to remain PDF/A compliant.
Click Apply to write the metadata.
Save the document.

Tip: Hover over any control to see a tooltip explaining what it does. Use the Remove button to strip all TDMRep metadata from the document.

Batch Processing Multiple Files

Go to Extensions > TDM Reservation > TDM Reservation (Batch)...
Add files using:
- Add Files... – Select one or more PDF files
- Add Folder... – Add all PDFs from a folder (optionally including subfolders)
Click Check Status to see the current TDMRep metadata for each file (displayed in the Reservation and Policy URL columns). This is read-only and does not modify any files.
Configure the Reservation and Policy URL settings.
Click Apply to All to process all files in the list.
The progress bar shows processing status. A summary is displayed when complete.

Tip: Use Check Status to audit a folder of PDFs and see which ones already have TDMRep metadata before applying changes.

Note: Batch processing opens, modifies, and saves each file automatically. Make sure the files are not open in Acrobat or other applications. Consider backing up your files before batch processing.

Policy URL

When reservation is set to 1 (rights reserved), you can optionally provide a Policy URL that points to a machine-readable TDM licensing policy. This tells AI crawlers where to find your terms for text and data mining.

The Policy URL field is optional. Leave it blank if you don't have a policy file yet — setting reservation to 1 alone is enough to signal that TDM rights are reserved and crawlers should contact you for terms.

Checking the URL

The Check button next to the Policy URL field sends an HTTP request to the URL and reports whether the server is reachable. It's a sanity check — useful for spotting typos or expired hosts before you embed the URL into many PDFs.

The check is informational only. You can still click Apply even if the check fails. This is intentional: you may want to embed the URL before deploying the policy file, or the policy host may simply be temporarily unreachable. The plug-in does not validate the URL's content or syntax beyond requiring an http:// or https:// scheme.

Sample Policy URL

A typical policy URL looks like:

https://yourcompany.com/policies/tdm-policy.json

See the section below for what the JSON file at that URL should contain.

Generating the Policy JSON

The plug-in includes a built-in generator that creates a W3C-compliant TDM policy JSON file from a few form fields. Go to Extensions > Mapsoft > TDM Reservation > Create Policy Document...

Which fields are required?

The W3C TDMRep specification only strictly requires the Policy URI (the uid); every other field on the dialog is optional per the standard. The labels in the dialog show this directly — (required) next to the Policy URI and (optional) next to all the others.

That said, a policy with no rights-holder details is technically valid but practically useless — crawlers cannot contact you for licensing. The plug-in shows a non-blocking warning before saving in that case.

Field	Spec status	What it does
Policy URI	Required	A stable URI identifying this policy (becomes the `uid`). Conventionally the URL where you'll host the JSON, but the W3C spec does not require it to be dereferenceable or to match the hosting URL — see "Three URLs to keep straight" below.
Rights Holder URI	Optional	A URI identifying the rights holder, typically your homepage.
Full name	Optional	Becomes `vcard:fn`.
Email	Optional	Becomes `vcard:hasEmail`; `mailto:` prefix is added automatically.
Website	Optional	Becomes `vcard:hasURL`.
Target URL	Optional	Limits the policy to a specific URL or domain. Leave blank for global scope.
Duty	Optional	None = unconditional permission; Obtain consent = crawler must contact you; Compensate = a fee applies.

Workflow

Open the dialog from the menu above.
Fill in at minimum the Policy URI; provide as much rights-holder detail as you want crawlers to see.
The Preview pane updates live as you type so you can see the JSON. Empty optional fields are omitted from the output.
Click Save... to validate and write the file (default name tdm-policy.json).
Host the JSON on your web server at a URL of your choice, and paste that URL into the Policy URL field on the main TDM Reservation dialog. By convention this matches the Policy URI you entered, but it doesn't have to (see below).

Three URLs to keep straight

The W3C spec separates a few concepts that look similar but aren't the same thing:

What	Where	What it represents
`uid` (this dialog's "Policy URI")	Inside the JSON document	A stable identifier for the policy. The spec says it "is not required... to be dereferenceable" — it doesn't have to resolve over HTTP, and doesn't have to match where you actually host the file. Think of it like a DOI or canonical URL.
JSON hosting location	On your web server	Wherever you actually upload `tdm-policy.json`. You're free to put it anywhere reachable.
`tdm:policy` (main dialog's "Policy URL")	Inside each PDF's XMP metadata	The URL crawlers will fetch when they encounter the PDF. This must resolve to the JSON file. It's typically the same as the hosting URL.

For a small site all three are usually the same string. They split up when you have versioned policies, content delivered through a CDN, or a canonical identifier kept distinct from the physical hosting URL.

Note: The generator covers the common case. If you need an unusual policy structure (multiple permissions, complex constraints, additional ODRL terms), hand-edit the saved JSON or write the file from scratch using the W3C TDMRep specification § 5 as the reference.

Policy Format

The canonical reference for the policy document is Section 5 of the W3C TDMRep specification (see also the editor's draft). The policy must be served as application/json or application/ld+json and follows a profile of the Open Digital Rights Language (ODRL) 2.2. The minimal example given by the W3C specification is:

{
  "@context": [
    "http://www.w3.org/ns/odrl.jsonld",
    "http://www.w3.org/ns/tdmrep.jsonld"
  ],
  "@type": "Offer",
  "profile": "http://www.w3.org/ns/tdmrep",
  "uid": "https://provider.com/policies/1",
  "assigner": {
    "uid": "https://provider.com",
    "vcard:fn": "Provider",
    "vcard:hasEmail": "mailto:contact@provider.com"
  },
  "permission": [
    { "action": "tdm:mine" }
  ]
}

Note in particular that vcard:hasEmail must use the mailto: URI scheme, not a bare email address.

A more complete real-world policy — using your own domain and adding a duty requiring crawlers to obtain consent — might look like:

{
  "@context": [
    "http://www.w3.org/ns/odrl.jsonld",
    "http://www.w3.org/ns/tdmrep.jsonld"
  ],
  "@type": "Offer",
  "profile": "http://www.w3.org/ns/tdmrep",
  "uid": "https://yourcompany.com/policies/1",
  "assigner": {
    "uid": "https://yourcompany.com",
    "vcard:fn": "Your Company Name",
    "vcard:hasEmail": "mailto:licensing@yourcompany.com",
    "vcard:hasURL": "https://yourcompany.com/tdm/"
  },
  "permission": [
    {
      "target": "https://yourcompany.com/",
      "action": "tdm:mine",
      "duty": [
        { "action": "obtainConsent" }
      ]
    }
  ]
}

Key Fields

Field	Description
`uid`	A unique identifier for this policy, typically the URL where the policy is hosted.
`assigner`	The rights holder's details — name, email, and website.
`permission`	What mining actions are allowed. The `duty` array specifies conditions such as `obtainConsent` (contact the publisher) or `compensate` (a licensing fee applies).

Hosting the Policy

Host the JSON file on your web server at a stable URL, for example:

https://yourcompany.com/policies/tdm-policy.json

Ensure the server returns a Content-Type of application/json. The URL should be long-lived, as it will be embedded in every PDF you process.

Tip: If you don't have a policy file yet, you can set reservation to 1 with no policy URL. This signals that TDM rights are reserved and crawlers should contact you for terms. You can add the policy URL later.

Note: The plug-in remembers your last-used policy URL, so you only need to type it once. It is stored in the Windows registry at HKEY_CURRENT_USER\Software\Mapsoft\TDMRep.

PDF/A Extension Schema

When the Include PDF/A extension schema option is checked, the plug-in embeds a PDF/A extension schema definition alongside the TDMRep properties. This is required for PDF/A documents, because PDF/A validators will raise errors if custom XMP properties are present without a corresponding schema definition.

The extension schema is based on the PDF Association's recommended TDMRep schema.

Technical Details

The plug-in writes TDMRep properties into the document's XMP metadata stream (the /Metadata entry in the document catalog). The XMP fragment looks like:

<rdf:Description rdf:about=""
      xmlns:tdm="http://www.w3.org/ns/tdmrep/">
   <tdm:reservation>1</tdm:reservation>
   <tdm:policy>https://example.com/policy.json</tdm:policy>
</rdf:Description>

When the extension schema is included, an additional rdf:Description block is added that describes the TDMRep namespace for PDF/A validators, following the pdfaExtension:schemas pattern.

About

Mapsoft TDMRep is a free plug-in from Mapsoft Computer Services Limited.

Mapsoft TDMRep - User Guide

Overview

What is TDMRep?

Using the Plug-in

Setting TDM Reservation on a Single Document

Batch Processing Multiple Files

Policy URL

Checking the URL

Sample Policy URL

Generating the Policy JSON

Which fields are required?

Workflow

Three URLs to keep straight

Policy Format

Key Fields

Hosting the Policy

PDF/A Extension Schema

Technical Details

Further Reading

About