Great documentation shouldn’t be an afterthought — it should be a natural outcome of well-defined data contracts.

This tutorial is the last of a series of four, explaining how you can use and get value from Data Contracts & Data Products in a very hands-on way. Over ninety people participated in the early alpha and beta in May and June 2025, with testimonies such as the one from Tom De Wolf: A well-structured format to specify a data contract is the foundation to generate pretty print documentation for humans, and for platform automation or other processes towards systems. Don’t start describing data contracts in Word or any other unstructured document; make them structured from the start. Make them human and machine-readable.

Check out my list of data contracts & data products tutorials on Medium; you’ll find the link to the other three tutorials and the surveys. The associated GitHub repo contains extra information. When you finish the four tutorials and four surveys, you will receive a digital badge to show your recently acquired knowledge.

In this tutorial, you’ll learn how to turn your existing data contract into clean, readable, and up-to-date documentation — automatically. With just a few API calls, you can go from raw YAML to a polished PDF your users will actually want to read.

Let’s make your contracts speak for themselves.

Data Contracts can help you standardized documentation and keep it up-to-date.

In this tutorial, I will demonstrate how you can turn a data contract into a nice, readable documentation that will always be up to date.

There is so much information in a data contract that it would be a shame to leave it there, right?

Setting up the playground

This tutorial assumes you did the first tutorial, where you created a data contract.

For simplicity, as I did previously, I will export all key values as environment variables, so it will be easier to copy/paste the curl calls. Remember, your values are different…

export BITOL_URL=https://cloud.jgp.ai/api
export BITOL_USER_PW=BitolRu7ez!
export BITOL_USER_EMAIL=jgp@jgp.net
export BITOL_API_KEY=97d09209-9021-4b24-89a9-620aae063d40
export BITOL_CONTRACT_ID=34cae6d7-7648-38b2-8f66-8db79e1e2ce4

Reminder: the repository and resources are available at https://github.com/jgpdotai/cloud-services/.

Your First PDF

Let’s start with an ugly PDF. Getting a contract in another format is as easy as specifying the format on the URL!

Try it:

curl -X GET "$BITOL_URL/v1/contracts/$BITOL_CONTRACT_ID?format=PDF" 
  -H "X-API-KEY: $BITOL_API_KEY" 
  -H "X-USER-PASSWORD: $BITOL_USER_PW" 
  --output $BITOL_CONTRACT_ID.pdf

And now look at the PDF, you should see something like:

The format=PDF gives you a PDF version of the YAML defining a contract

Yeah, it’s ugly, but more than ugly, it is absolutely unusable for a business user.

Your Real First PDF

Let’s create a PDF that will be visually more appealing and efficiently help your users. The operation is a little slow, so be warned, but try:

curl -X GET "$BITOL_URL/v1/contracts/$BITOL_CONTRACT_ID?format=PrettyPDF" 
  -H "X-API-KEY: $BITOL_API_KEY" 
  -H "X-USER-PASSWORD: $BITOL_USER_PW" 
  --output $BITOL_CONTRACT_ID.pdf

And, after 30ish seconds, now look at the PDF, you should see something like:

A much nicer results with a clear table of content (okay, I added the gradient fill for Medium)

In this updated version, you have a clear table of contents, hyperlinks, key definitions, sections, a clear representation of the schema, and more.

This service is still experimental, and many sections are still marked as “coming soon.” They are being addressed, but feel free to raise them as an issue so I know which ones to prioritize.

Let’s Personalize

As much as you love jgp.ai (I know, thank you, you’re welcome), you may not want to use this logo and footer. As you may also be from outside the US (or Canada in this context), you may also prefer the metric system and A4 sheets of paper.

Uploading a logo is easy. You will need an SVG logo. Its width will be 20mm, so choose strategically. Run:

curl -X POST "$BITOL_URL/v1/logo" 
  -H "X-API-KEY: $BITOL_API_KEY" 
  -H "X-USER-PASSWORD: $BITOL_USER_PW" 
  -F "file=@resources/company-logo.svg"

If you get an error, you can overwrite your existing logo with force=true, as in:

curl -X POST "$BITOL_URL/v1/logo?force=true" 
  -H "X-API-KEY: $BITOL_API_KEY" 
  -H "X-USER-PASSWORD: $BITOL_USER_PW" 
  -F "file=@resources/company-logo.svg"

You can also modify:

  • The footer text.
  • The size of the paper: you can choose between letter and A4.

It is as simple as:

curl -X POST "$BITOL_URL/v1/pdf-settings" 
  -H "X-API-KEY: $BITOL_API_KEY" 
  -H "X-USER-PASSWORD: $BITOL_USER_PW" 
  -F "size=A4" 
  -F "footer=Generated by Bitol Services on jgp.ai"

Those settings are permanent; once you set them, you do not have to change them. You can now retrieve the personalized document:

curl -X GET "$BITOL_URL/v1/contracts/$BITOL_CONTRACT_ID?format=PrettyPDF" 
  -H "X-API-KEY: $BITOL_API_KEY" 
  -H "X-USER-PASSWORD: $BITOL_USER_PW" 
  --output $BITOL_CONTRACT_ID.pdf

And, in less than a minute, you will get:

Bonus points to the reader who will be able to find out why there is a bretzel there…

Although customizations are pretty limited for now (raise issues if you want more), these few simple calls deliver a clear standardized documentation that you can easily update by enhancing the contract.

A Virtuous Process

Let’s look at the entire process we followed here and how it can be integrated in a virtuous lifecycle.

In the first tutorial, you learned how to create a data contract from an existing asset. In this tutorial, you generated pretty documentation for your users. The next step is to be open to feedback from your users and enhance the documentation, not in Word, Confluence, or any other wiki, but in the contract itself, your source of truth for metadata.

A righthteous process for keep documentation rich, pleasing, standardized, and always up to date.

Better Contracts = Better Docs

What you just saw is only the beginning. The more complete and well-structured your data contract is, the richer and more helpful your documentation becomes.

Every field you describe, every usage note you add, every SLA or contact you define — it all contributes to creating a living document your consumers can trust and your team can maintain effortlessly.

Want prettier docs? Start by enriching your contract. Define purposes, clarify limitations, add context — it only takes a few lines, and the payoff is huge. So don’t stop at schemas. Make your contracts tell the full story. Your future self — and your users — will thank you.

Current limitations of the pretty PDF documents. Rendering will be available or enhanced soon for:

  • Tags.
  • Custom properties.
  • Authoritative definitions.
  • Mapping between the logical information and the physical implementation.
  • Data quality rules.
  • Support channels.
  • Pricing.
  • Bug in displaying the current owner.
  • Security.
  • Service-level agreements (SLA) outside of product lifecycle.
  • Infrastructure.

Making Pretty Documentation from Data Contracts was originally published in Data Mesh Learning on Medium, where people are continuing the conversation by highlighting and responding to this story.

Leave a Reply

Your email address will not be published. Required fields are marked *