a_project_json.asc #1

[[appendix_project_json]]
=== Appendix A: Project JSON

Projects relate branches of revisions with other structures, like groups, to help create the foundation for general workflows.

The content type of the project JSON is `application/vnd.perforce.project.v1+json`.
You can specify the content type without the version string, e.g., `application/vnd.perforce.project+json`.
This may be useful in cases where you can handle possibly different versions of JSON, say, for migration.

==== JSON structure

A project document is a JSON object that contains the following properties.

[cols="3*", options="header"]
|===
| Property
| Required
| Description

| `id`
| Yes
| The `id` should be a unique string.
  It should be safe to put in as a single path element in a URI.

| `name`
| Yes
| A string suitable for display of the project.

| `server`
| Yes
| A P4 URL that indicates how to connect to the p4d instance to retrieve the files of the project.
  For example, `p4://P4CHARSET=auto@perforce.myinstance.com:1666`

| Extension ID
| No
| Each extension ID will map to a particular JSON object type defined for each extension.
  For example, there may be a property named `helixCloud` that maps to the JSON defined in <<appendix_helix_cloud>>.
|===

==== Project Extensions

Each project extension should have a simple string ID, e.g., `helixCloud`, `gitFusion`.

Project extensions should always define a `contentType` property that is a versioned MIME content type.
For example, `application/vnd.perforce.helixCloud.v1+json`.