Versions and lifecycle
You change fare data by creating a new version of an element and sending it through a lifecycle: draft, test in the staging environment, and published in production. Each version has effective dates that say which travel dates it applies to. The API enforces the rules between elements, so a product can never be published with rules that are not published for the same dates.
Elements, versions and effective dates
Three concepts work together. They are related, but they are not the same thing:
- An element is a product, a parameter, a fare table or a sales package. It has a stable
NeTEx id,
id, for exampleEXA:PurchaseWindow:1b7d4c2a. Other elements refer to it by this id. - A version is one edition of the element's content. You create a version, edit it while it
is a draft, and send it through the lifecycle. A version is identified by
versionId, which is{version}in paths. When it is published, it gets a version number,versionNumber. - The effective dates,
validBetween, are the travel dates a version applies to. You set them when you send the version to test and when you publish it.
An element has one or more versions, and each version has one set of effective dates. The effective dates say which travel days the version is valid for.
Effective dates (validBetween)
The effective dates are written like this:
Code
fromDateis the first day the version applies.toDateis the last day the version applies. The date is inclusive. Leave it out for a version with no end.- The dates are about travel. They say when a product can be used, not when it can be sold.
A version keeps its id when you change its effective dates. You can propose a version again with
other dates, and you can end a published version with expire. It is still the same version.
The effective dates of an element's published versions follow each other with no overlaps and
no gaps. A version that follows another starts on the day after the earlier version's toDate:
| Version number | fromDate | toDate |
|---|---|---|
| 1 | 2027-01-01 | 2027-06-30 |
| 2 | 2027-07-01 | (open) |
Statuses
A version has one of four statuses. The status says which Entur environment the version is available in:
| Status | Available in environment | Can you change the content? |
|---|---|---|
DRAFT | None. Work in progress. | Yes |
PROPOSED | Staging, for testing. | No |
VERSIONED | Production. This is the published status. | No |
DEPRECATED | None. Replaced by another version. Set by the API, never by you. | No |
You create all fare data in the production API. The status decides where it is used: a
PROPOSED version is only used in the staging environment, so you can test it before it reaches
travellers.
Some rules follow from the statuses:
- Only a
DRAFTversion can be changed (PUT) or deleted (DELETE). - To change something that is under test or published, create a new version with
POST /{id}. A new version doesn't inherit anything from earlier versions, so send the complete content, including all references. It starts as aDRAFT. - An element can have only one version in progress (
DRAFTorPROPOSED) at a time.
Operations
A version moves between statuses through four operations. Each one is a POST to
/{id}/{version}/<operation> on the element:
| Operation | Allowed from | Resulting status | Request body |
|---|---|---|---|
propose | DRAFT, PROPOSED | PROPOSED | validBetween (required) |
withdraw | PROPOSED | DRAFT | Optional |
publish | PROPOSED | VERSIONED | validBetween (required) |
expire | VERSIONED | VERSIONED | toDate (required) |
What each operation does:
proposemakes the version available in the staging environment, with the effective dates you give it.withdrawtakes the version out of staging and back toDRAFT, so you can change it.publishmakes the version available in the production environment and gives it a version number. You give the effective dates again. The dates you used for testing are not carried over.fromDatecan't be in the past. Today is allowed.expiresets the last effective date (toDate) of a published version. It can't be in the past. ThefromDateof a published version can't change.
All four operations also take note, externalReferenceName and externalReferenceUrl. These
are written to the element's audit log. Use them to record why you made the change, for example
with a link to your own case.
When you publish a version, the API keeps the effective dates of the published versions continuous:
- If the previous published version has no end, the API sets its
toDateto the day before the new version'sfromDate. - If the previous published version has exactly the same effective dates, the API sets it to
DEPRECATED.
Both changes are written to the audit log as automatic changes.
Coverage rule
A product refers to rules and parameters, such as a purchase window or a usage validity period (how long the product can be used after purchase or activation). It refers to them by NeTEx id, not by version. On each travel date, the product uses the published version of the parameter whose effective dates include that date.
The API therefore checks that each parameter has published versions for all of the product's effective dates. The full check is made when you publish:
| When | What is checked |
|---|---|
| You create or update a draft | Only that each referenced parameter exists |
| You propose the product | Nothing more than for a draft |
| You publish the product | The effective dates of the parameters' published versions together cover the product's effective dates, and the product has a usage validity period |
The coverage rule is checked when you publish. A product with no toDate needs parameters with
no toDate too.
Propose the parameters before the product anyway, so that everything the product depends on is available in the staging environment while you test.
The rule works in both directions. You can't end a published parameter earlier than a published product that depends on it.
Publish order
Because of the coverage rule, work from the bottom up. Publish what a product depends on before the product, and the product before the sales packages that contain it.
- Propose the parameters, the prices and the product, in that order.
- Propose the sales package that contains the product. A sales package refers to a specific
version of the product by its
versionId. - Test the whole package in staging. Travellers buy sales packages, so this is the first point where you can try a purchase.
- Publish in the same order: parameters, prices, product, sales package.
If you publish a product before a parameter it refers to, the API rejects the request with the coverage error shown in Errors.
Price changes
A product refers to its fare tables by NeTEx id, not by version. When a new version of a fare table becomes valid, the product uses the new prices from that day. The product doesn't need a new version.
To change a price, create a new version of the fare table with the new price and a fromDate
for when it applies, then propose and publish it.
Other operators can include your products in their own sales packages. When you change a product or its prices, the change also applies wherever your product is sold together with theirs.
Errors
The API returns errors as RFC 9457 problem details, with content type
application/problem+json. The detail field says what went wrong. When the error is about a
parameter the request refers to, the response also has field, the field in your request, and
reference, the id that failed:
Code
Most errors come from the rules on this page:
| Status | Typical cause | See |
|---|---|---|
400 | A referenced parameter doesn't exist, or isn't published for all of the product's effective dates. | Coverage rule |
400 | The effective dates are invalid, for example reversed or starting in the past when you publish. | Effective dates |
409 | The operation isn't allowed from the version's status, the element already has a version in progress, or you tried to change a version that isn't a draft. | Statuses, Operations |
409 | The effective dates overlap or leave a gap to another published version. | Effective dates |
403 | The element belongs to another organisation. | Fare data – Access |