Refactor entity schema to separate data model from API documentation

[NateWr]

Describe the problem you would like to solve

The REST API documentation is generated directly from the entity schema files. When generating documentation, the tool reads the readOnly, writeOnly and apiSummary properties to display request and response details. The same schema files are used to determine the properties accepted and returned with API requests.

This means that the entity schema files define two things that sometimes don't align:

1. What properties can be edited on an entity.
2. What properties can be read or written in the API.

For example, when marking a property readOnly, the API documentation removes this property from the request body schema (example). However, this also means that the EntityDAO will not write this property to the database.

This causes problems when we want to restrict or permit a property in the API but want to handle it differently at the EntityDAO level. An example would be the status property of the submission. We need to be able to edit this property during operations in the code (eg - when an editorial decision is made or a submission is published). However, we don't want this property to be editable through the /submissions/<id> API endpoint.

This is not hard to implement in the code. But the result is that the API documentation is incorrect (the status appears to be an accepted property when adding or editing a submission, but it is not).

Describe the solution you'd like

We will need to separate out how we define an entity's core data model, including validation, from how we define an entity's REST API endpoints. I can think of three approaches depending on how much work we want to put in.

1. Move API definitions to a separate attribute of each property

Right now properties are each marked readOnly or writeOnly:

{
	"properties": {
		"a": {
			"type": "integer",
		},
		"b": {
			"type": "string",
			"readOnly": true,
		},
		"c": {
			"type": "integer",
			"writeOnly": true
		}
	}
}

We could leave readOnly and writeOnly to define the EntityDAO behavior and move API documentation to a new attribute of each property:

{
	"properties": {
		"a": {
			"type": "integer",
			"api": [
				"GET",
				"POST",
				"PUT"
			]
		},
		"b": {
			"type": "string",
			"readOnly": true,
			"api": [
				"GET",
			]
		},
		"c": {
			"type": "integer",
			"writeOnly": true,
			"api": [
				"POST",
				"PUT"
			]
		}
	}
}

2. Separate API definitions from the properties

Another approach would be to keep the API definitions separate from the properties list.

{
	"properties": {
		"a": {
			"type": "integer"
		},
	},
	"api": {
		"properties": {
			"b": {
				"type": "string"
			},
			"c": {
				"type": "integer"
			}
		},
		"GET": ["a", "b"],
		"POST": ["a", "c"],
		"PUT": ["a", "c"],
	}
}

3. Refactor the entity schema's to use PHP

A more comprehensive change would be to define entity schemas in PHP and adapt EntityDAOs to work from that. This would be a more comprehensive change and would probably be best if adopting a third-party library of some kind.

However, if we move in this direction we will need some way to generate accurate REST API documentation which distinguished between the entity's data model and what is accepted in the API.

Who is asking for this feature?

I've had to add a new attribute, writeDisabledInApi, to restrict editing the submission through the API, as outlined in this comment. It's a short-term solution for this one problem, but probably not great for the long-term.

Additional information

Whatever approach we adopt must meet the following requirements of the schema system:

1. An entity's schema can be extended by each app (OJS, OMP, OPS).
2. An entity's schema can be extended by a plugin.
3. Validation rules can be changed by each app or a plugin.
4. An entity's schema can be used to generate accurate documentation for the REST API (an OpenAPI v3 JSON file).