Implementation/64530 extend project api to consider calculated values

[EinLama]

Ticket

https://community.openproject.org/wp/64530

What are you trying to accomplish?

Offer a way to interact with calculated values using the API.

There were two possibilities of representing calculated values in the API:

1. As a separate resource that can (but is not required to) be embedded into a project representation. It has its own ID and API, offering ways to read and write it. This is done for custom fields such as Version or User, where you can also do a lot with the resources apart from enabling or disabling them.
2. As a property of projects. This is done for custom fields such as Integer, Float or Boolean.

After multiple discussions and brainstorming, I went with the second approach. The main reason is that calculated values have a assigned custom value that is a constant - not an ID to relating to another model. The latter is required to properly build an API around it. We don't get that here, so we would have to either blow up the entire implementation by defining an actual model for calculated values - or we need to treat it like a pseudo-resource within the API. I didn't like either of these options. The only thing that sets calculated values apart from a float is that they contain a formula and may produce errors. This is not enough to justify the mention measures. Meaning:

• Calculated values behave a lot like project custom fields of type float:
  • They are returned as a floating point value if a value could be calculated.
  • If no value could be calculated, they are rendered as nil.
• Within the project schema, calculated values are represented with their own type, they will also include their formula.
• Following our past implementations, the feature flag is not checked when reading calculated values. Within the API, there is no way to create calculated values, see the caveats section. As a consequence, the feature flag plays no role in this PR.
  • Conditional read access will be a concern once the Enterprise Token is added.
• The current PR does not support error messages. This will be a concern of the upcoming error handling work package.

Caveats

• The project custom field support within our API is very basic. There is no way to edit project custom fields like admins can within the web UI. You cannot edit them, you cannot disable them per project. You can only enable them per project implicitly by assigning a value to them.
• Calculated values have no writable value - therefore you cannot enable them by assigning a value to them.
• Since project custom fields cannot be edited, there is no way to edit the formula of a calculated value via the API.

All of the above could be addressed by providing a proper project custom field API that offers mostly the same features as the Web UI. The current implementation aims to integrate calculated values into the current API structure as well as possible.

Examples

Project schema response (excerpt):

{
  "_type": "Schema",
  "_dependencies": [],
  "id": {
    "type": "Integer",
    "name": "ID",
    "required": true,
    "hasDefault": false,
    "writable": false,
    "options": {}
  },
  "name": {
    "type": "String",
    "name": "Name",
    "required": true,
    "hasDefault": false,
    "writable": true,
    "minLength": 1,
    "maxLength": 255,
    "options": {}
  },
  "_attributeGroups": [
    {
      "_type": "ProjectFormCustomFieldSection",
      "id": 4,
      "name": "Project attributes",
      "attributes": [
        "customField17",
        "customField20",
        "customField21"
      ]
    }
  ],
  "customField17": {
    "type": "Float",
    "name": "float value",
    "required": false,
    "hasDefault": false,
    "writable": true,
    "options": {
      "rtl": null
    }
  },
  "customField20": {
    "type": "CalculatedValue",
    "name": "calc val",
    "required": false,
    "hasDefault": false,
    "writable": true,
    "options": {
      "rtl": null
    },
    "formula": "{{cf_17}} * 2"
  },
  "customField21": {
    "type": "Version",
    "name": "version field",
    "required": false,
    "hasDefault": false,
    "writable": true,
    "location": "_links",
    "_links": {}
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects/schema"
    }
  }
}

Project response (excerpt):

{
  "_embedded": {
    "status": {
      "_type": "ProjectStatus",
      "id": "on_track",
      "name": "On track",
      "_links": {
        "self": {
          "href": "/api/v3/project_statuses/on_track",
          "title": "On track"
        }
      }
    },
    "customField21": {
      "_type": "Version",
      "id": 25,
      "name": "v1",
      "description": {
        "format": "plain",
        "raw": "v1 description",
        "html": "<p>v1 description</p>"
      },
      "startDate": "2025-09-01",
      "endDate": "2025-09-15",
      "status": "open",
      "sharing": "none",
      "createdAt": "2025-09-01T13:10:07.687Z",
      "updatedAt": "2025-09-01T13:10:07.687Z",
      "_links": {
        "self": {
          "href": "/api/v3/versions/25",
          "title": "v1"
        }
      }
    }
  },
  "_type": "Project",
  "id": 4,
  "identifier": "demo-project",
  "name": "Demo project",
  "customField17": 98.0,
  "customField20": 196,
  "_links": {
    "self": {
      "href": "/api/v3/projects/4",
      "title": "Demo project"
    },
    "customField21": {
      "title": "v1",
      "href": "/api/v3/versions/25"
    },
    "parent": {
      "href": null
    }
  }
}

Merge checklist

• Added/updated tests
• Added/updated documentation in API
• Tested major browsers (Chrome, Firefox, Edge, ...)