# Versions and lifecycle

:::lead
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 example `EXA: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:

```json
{
  "validBetween": {
    "fromDate": "2027-01-01",
    "toDate": "2027-06-30"
  }
}
```

- `fromDate` is the first day the version applies.
- `toDate` is 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 `DRAFT` version 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 a `DRAFT`.
- An element can have only one version in progress (`DRAFT` or `PROPOSED`) 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) |

```mermaid
stateDiagram-v2
    [*] --> DRAFT: create version
    DRAFT --> PROPOSED: propose
    PROPOSED --> PROPOSED: propose (new effective dates)
    PROPOSED --> DRAFT: withdraw
    PROPOSED --> VERSIONED: publish
    VERSIONED --> VERSIONED: expire
    VERSIONED --> DEPRECATED: replaced (automatic)
    DRAFT --> [*]: delete
```

What each operation does:

- `propose` makes the version available in the staging environment, with the effective dates you give it.
- `withdraw` takes the version out of staging and back to `DRAFT`, so you can change it.
- `publish` makes 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. `fromDate` can't be in the past. Today is allowed.
- `expire` sets the last effective date (`toDate`) of a published version. It can't be in
  the past. The `fromDate` of 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 `toDate` to the day before the new version's `fromDate`.
- 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.

```mermaid
flowchart LR
    P["Rules and parameters"] --> FT["Prices<br/>FareTable"] --> SP["Product"] --> SOP["Sales package<br/>SalesOfferPackage"]
```

1. Propose the parameters, the prices and the product, in that order.
2. Propose the sales package that contains the product. A sales package refers to a specific
   version of the product by its `versionId`.
3. Test the whole package in staging. Travellers buy sales packages, so this is the first point
   where you can try a purchase.
4. 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](#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.

:::warning
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:

```json
{
  "title": "Invalid parameter reference",
  "status": 400,
  "detail": "purchaseWindowRef 'EXA:PurchaseWindow:7d2e…': Eligible parameter versions do not cover 2027-01-01 to open end for VERSIONED",
  "field": "purchaseWindowRef",
  "reference": "EXA:PurchaseWindow:7d2e…"
}
```

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](#coverage-rule) |
| `400` | The effective dates are invalid, for example reversed or starting in the past when you publish. | [Effective dates](#effective-dates-validbetween) |
| `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](#statuses), [Operations](#operations) |
| `409` | The effective dates overlap or leave a gap to another published version. | [Effective dates](#effective-dates-validbetween) |
| `403` | The element belongs to another organisation. | [Fare data – Access](/docs/partner-services/fare-data#access) |
