Contentful Schema Diff tool

Hi All,

Here at Watermark Community Church we’ve been developing our toolchain around Contentful for the last several months, and felt it was time to publicize one of our most important tools. We call it contentful-schema-diff.

The purpose of this tool is to inspect two spaces and determine the differences in their content-types, and then to output a migration file compatible with the contentful-migration CLI.

In our workflow, these migration scripts are stored in the db/migrate directory. We have our own fork of contentful-migration, which only runs migration files that have not already been run in the space. The record of these migrations is stored in a special content type in the space.

All of these tools are open-source at the moment, and we will continue supporting them as long as we are on the Contentful platform for our primary CMS. Pull requests welcome!


Hey @gburgett,

Congrats on project and thank you so much for sharing it with us!

Thanks for all your work @gburgett! Looks awesome.

@gburgett : Thanks for this tool. I was try to execute it but was getting error. Am i doing something wrong.

For my space, I have “master” and “Development” environment, which is my feature / staging environment. And wanted to compare diff between master & development env.


I am running the below command :
contentful-schema-diff --from “space-id” --to Development --token “contentful management token”

Getting below error :
[warning] Connection error occurred. Waiting for 1944 ms before retrying…
[warning] Connection error occurred. Waiting for 2562 ms before retrying…
[warning] Connection error occurred. Waiting for 3506 ms before retrying…
[warning] Connection error occurred. Waiting for 4691 ms before retrying…
[warning] Connection error occurred. Waiting for 6235 ms before retrying…
{ Error: getaddrinfo ENOTFOUND
at errnoException (dns.js:50:10)
at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:92:26)
code: ‘ENOTFOUND’,
errno: ‘ENOTFOUND’,
syscall: ‘getaddrinfo’,
hostname: ‘’,
host: ‘’,
port: ‘443’,

Hey @mainak4u.007 , looks like you’re using it correctly! It seems that the tool could not connect to the contentful API. Can you connect using a curl request? Try executing this to make sure it’s not a connection issue (Make sure you replace the $CONTENTFUL_MANAGEMENT_TOKEN and $CONTENTFUL_SPACE_ID):

curl -H “Authorization: Bearer $CONTENTFUL_MANAGEMENT_TOKEN”$CONTENTFUL_SPACE_ID/environments/Development/content_types

@dev2 Thanks for the suggest. Yes, it was connectivity issue. It worked from me now and able to see the TS files showing difference.

After getting the diff file is TS, I am trying to migrate it and getting below error. What could be wrong here.

Command :
node_modules/.bin/ts-node node_modules/.bin/contentful-migration -s xxxxxxxxxx -a xxxxxxxxxxxxxxxx 20190529202527_generated_diff_menu.ts

? Do you want to apply the migration Yes
❯ Update Content Type menu
:heavy_multiplication_x: Making requests (2/2)
→ Batch failed
Update editor interface for Content Type menu
:rotating_light: Migration unsuccessful
Batch failed

Error: {"status":"Forbidden","message":"Forbidden","details":{"reasons":["accessTokenScope","You do not have permissions to update on ContentType, please contact your administrator for more information."]},"url":""}

Hi @mainak4u.007, it looks like your user doesn’t have permissions to change content types in your space. I’d check two things:

  1. does your content management token (the parameter to the -a flag) begin with CFPAT- ? If not, you are using the wrong access token.
  2. does your user have the “admin” permissions in the space? Here is a description of what the various roles can do:
1 Like

@gburgett thanks for the suggestion. Yes, my issue was - Point 1. Some issue was happening with my content management token … when i try to generate from CLI contentful login command and then pasting the token, it was not working… later i tried generating one in contentful site, created .contentfulrc.json and pasted that token , it started working :slight_smile:

One question, do this tool shows the difference of content as well.

@gburgett I am using contentful schema diff tool but getting the below error when i am trying to compare 2 environments

npx contentful-schema-diff --from 37lvxp3wt7oq/dev-2 --to 37lvxp3wt7oq/dev-3 --token na-ttkiP7bcKoCxODCFHSHS7XDguHPUEOsxrYy-hAKA --one-file
Error: Diff produced a “~” with a non-diff obj:
at C:\Users\viswa.telagamsetty\AppData\Roaming\npm\node_modules\contentful-schema-diff\dist\modify.js:151:43
at Array.forEach ()
at Object. (C:\Users\viswa.telagamsetty\AppData\Roaming\npm\node_modules\contentful-schema-diff\dist\modify.js:125:32)
at fulfilled (C:\Users\viswa.telagamsetty\AppData\Roaming\npm\node_modules\contentful-schema-diff\dist\modify.js:5:58)

because of this error file is not getting the closing bracket and there is one more issue if i am trying to close the curly brace and try to run the migration script on the file it was showing because of default_value your file cannot be migrated. If i have removed that than it is working.

We are trying to do the jenkins CI/CD by using this package.

Can you please help why it was happening

Hey @viswa.telagamsetty !

Unfortunately the tool is not smart enough to handle 100% of all possible migrations. It works great for about 95% of cases, and then you have to manually edit the migrations. For this reason I advise that you do not run the tool in an unattended automatic process inside your CI/CD.

Our team uses this package to create migrations locally, and then we check them in to our source code and include the final migrations as part of a pull request.

Of course you are always welcome to fork and improve the tool! I would welcome any pull requests at