Attachment files
Certain entities might have attachments associated with them. An attachment is comprised of a single file as well as additional data and derived file metadata.
At the moment there are four kinds of attachments:
- StanForD attachments
- Climate data attachments
- Vegetation data attachments
- Generic attachments
StanForD attachments
These attachments represent forest machine data files in the StanForD format.
There are two editions of the format: the initial one retroactively called StanForD classic, based on ASCII files; and the modern one called StanForD 2010, based on XML files. Note that each edition has its own versioning and that classic is no longer being updated.
Attachments can be created with files of both editions. Based on the file extension, the boolean attribute classic will be set. In addition, and as indicated in the StanForD 2010 specification, files with the extension suffix z (zip-compressed) are also accepted, with the boolean attribute compressed being set to true.
File size limit for all StanForD files: 25 MB
The corresponding Media Types when downloading these files are the following:
| Kind | Media Type |
|---|---|
| Classic | application/octect-stream |
| 2010 (uncompressed) | text/xml |
| 2010 (compressed) | application/zip |
Other than the file extension, no further verification of StanForD files is done.
Climate data attachments
These attachment files represent tables (as CSV) or plots (as PNG) with the main climatological characterization of the forest operations used during the project demonstrations.
Both climate tables and plots are organized by temporal resolution (i.e., daily, monthly, yearly), temporal coverage (on a yearly basis), and are either anomalistic (i.e., they concern climate anomalies based on relative values) or not (i.e., measured values).
File size limit for all climate data files: 10 MB
The corresponding Media Types when downloading these files are the following:
| Type | Media Type |
|---|---|
csv | text/csv |
png | image/png |
Upon download, the filename is automatically generated, based on its forest operation, temporal resolution and coverage, anomalistic value, and type.
CSV schema
Tables must be in CSV, must have a header row, no quote characters must be used, and the separator must be a comma. Columns must be the following:
| Name | Description | Unit/format |
|---|---|---|
datestamp | Date of reference | YYYY-MM-DD |
temperature_max | Maximum temperature | degree Celsius (Cel) |
temperature_min | Minimum temperature | degree Celsius (Cel) |
temperature_mean | Mean temperature | degree Celsius (Cel) |
precipitation_cum | Cumulative precipitaion | millimeter (mm) |
The value of datestamp as a date of reference depends on the temporal resolution of the file:
| Temporal resolution | Description | Example datestamp |
|---|---|---|
daily | Day of reference | 2025-07-15 |
monthly | First day of reference month | 2025-07-01 |
yearly | First day of reference year | 2025-01-01 |
Verification
All plots must be in PNG format. During upload, the file binary signature is used to verify that it's a PNG, irrespective of its name and extension.
All tables must be in CSV format, irrespective of its name and extension, and the header row must be exactly the following line:
datestamp,temperature_max,temperature_min,temperature_mean,precipitation_cum
Vegetation data attachments
These attachment files represent tables (in CSV format) with the Normalized Difference Vegetation Index (NDVI) for a given subcompartment that belongs to a demo forest operation.
There is at most one vegetation data attachment (and file) per subcompartment. Hence, the ID of the subcompartment also identifies the vegetation data attachment.
In addition, unlike other attachment files, when making multiple POST requests with the same subcompartment ID —and if the respective request files are valid— the first request
will create the attachment record and file, as well as set the record's start_date and end_date; subsequent requests will append their contents to the existing attachment file and update the record's end_date.
If successful, the POST response status will be either:
- 201: Created. Attachment file created.
- 204: No Content. Attachment file appended.
File size limit for vegetation data files on upload: 5 MB
The corresponding Media Type when downloading these files is: text/csv
Upon download, the filename is automatically generated, based on its subcompartment ID.
CSV schema
Files in CSV, must have a header row, no quote characters must be used, and the separator must be a comma. Irrespective of the file name and extension, columns must be the following:
| Name | Description | Format/range |
|---|---|---|
datestamp | Date of reference | YYYY-MM-DD |
ndvi | Normalized Difference Vegetation Index | -1.0 <= ndvi <= +1.0 |
Verification
The header row must be exactly the following line:
datestamp,ndvi
Upon both creation and appending, the first datestamp value of the CSV file must be lower than the last datestamp value.
Upon appending, the first datestamp value of the CSV file must be higher than the attachment's end_date (i.e., the latest datestamp value recorded).
Generic attachments
Generic attachments represent a diverse set of file types that can be associated with a given resource.
The following entities are all generic attachments that share the same endpoint logic.
- Forest Operation Attachment
- Sample Plot Attachment
- Tree Attachment
- Tree Log Attachment
- Sawline Attachment
Categories
File types of generic attachments can be grouped into the following categories:
- archive: compressed archive of one or multiple files
- data_exchange: format used mostly for data exchange
- geo_raster: geospatial raster graphic
- geo_vector: geospatial vector graphic
- image: visual representation format
- office: format mainly used in office productivity tools
File size limits are determined by category:
| Category | Limit |
|---|---|
geo_raster | 500 MB |
geo_vector | 250 MB |
| all other | 50 MB |
Types
The following are the accepted generic attachment types:
| Type | Title | Category | Extension | Media Type |
|---|---|---|---|---|
| 7z | 7z | archive | .7z | application/x-7z-compressed |
| csv | Comma-separated values | data_exchange | .csv | text/csv |
| doc | MS Word (binary) | office | .doc | application/msword |
| docx | MS Word (XML) | office | .docs | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| dwg | AutoCAD DWG | image | .dwg | image/vnd.dwg |
| geojson | GeoJSON | geo_vector | .geojson | application/geo+json |
| geotiff | GeoTIFF | geo_raster | .tiff | image/tiff; application=geotiff |
| gif | GIF | image | .gif | image/gif |
| jpeg | JPEG | image | .jpeg | image/jpeg |
| jpeg-wld | JPEG + World file | geo_raster | .zip | application/zip |
| json | JSON | data_exchange | .json | application/json |
| kml | KML | geo_vector | .kml | application/vnd.google-earth.kml+xml |
| kmz | Compressed KML | geo_vector | .kmz | application/vnd.google-earth.kmz |
| odt | Open Document Text | office | .odt | application/vnd.oasis.opendocument.text |
| Portable Document Format | office | application/pdf | ||
| png | PNG | image | .png | image/png |
| png-wld | PNG + World file | geo_raster | .zip | application/zip |
| ppt | MS PowerPoint (binary) | office | .ppt | application/vnd.ms-powerpoint |
| pptx | MS PowerPoint (XML) | office | .pptx | application/vnd.openxmlformats-officedocument.presentationml.presentation |
| rtf | Rich Text Format | office | .rtf | application/rtf |
| shz | Compressed Shapefile | geo_vector | .zip | application/zip |
| tiff | TIFF | image | .tiff | image/tiff |
| tiff-wld | TIFF + World file | geo_raster | .zip | application/zip |
| tsv | Tab-separated values | data_exchange | .tsv | text/tab-separated-values |
| txt | Plain text | office | .txt | text/plain |
| webp | WebP | image | .webp | image/webp |
| wpd | WordPerfect | office | .wpd | application/vnd.wordperfect |
| xls | MS Excel (binary) | office | .xls | application/vnd.ms-excel |
| xlsx | MS Excel (XML) | office | .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| zip | ZIP | archive | .zip | application/zip |
Verification
The first verification step is the extension of the file, which must be present in the table above. In addition, the following attachment types allow additional extensions:
- jpeg: .jpg
- tiff: .tif
Files with extension .json will have type geoson if the root is an object with the first property as follows :
"type" : "FeatureCollection"
TIFF images will have type geotiff if the required GeoTIFF GeoKeyDirectoryTag is present in the file.
Files with extension .zip will have the following types if the archive entries meet the respective conditions:
- shz: if there are three files with extensions .shp, .shx, and .dbf with the same basename
- jpeg-wld: if there are two files with the same basename, one JPEG and the other with extension .jpw, .jpgw, or .wld
- png-wld: if there are two files with the same basename, one PNG and the other with extension .pnw, .pngw, or .wld
- tiff-wld: if there are two files with the same basename, one TIFF and the other with extension .tiw, .tifw, or .wld
Finally, most type files will be verified based on the expected binary file signature.
Create attachments
Unlike most of the API, creation of attachments must be done via a POST request having content type multipart/form-data. In addition, each field must be prepended by the suffix attachment:, including the file itself which must be in the field file.
For illustrative purposes only, a possible command to create an attachment using cURL could be:
curl -F attachment:field="value" -F attachment:file=@localfilename.ext API_ENDPOINT_URL
Name fields
For attachments that allow setting a name, if the name field is not present, it will be set to the filename (without extension).
Boolean fields
Values of boolean fields must be one of the following case-sensitive strings (as with JSON): true or false.
Tag fields
For attachments with tags, upon creation they must be sent as single string separated by commas. For instance, in the case of cURL:
-F attachment:tags="tag1,tag2,tag3"
All tags will be converted to lowercase and white space will be trimmed.
Update attachments
Attachments only accept partial updates via a PATCH request with content type application/json, whose payload must have the root object attachment. This is because certain attributes of the attachment are automatically derived from the file itself.
To only update the attachment name, the request body could be:
{
"attachment": {
"name": "New Name"
}
}
To set an updatable attribute to null, you must explicitly do so. For instance, to set description to null and update tags:
{
"attachment": {
"description": null,
"tags": ["tag1", "tag2"]
}
}
If you want to replace the attachment file, you will need to delete the attachment first and then create a new one.
Download attachment files
Attachments contain an attribute url to access the file URL. The file will be sent with Content-Disposition set to attachment and filename set to the attachment name plus its type extension (see table above).
As with other API endpoints, an access token with Bearer Login Auth might be needed to download attachment files (e.g., for privacy reasons). However, it might be the case that setting the corresponding request header is not feasible, such as in the src attribute in img HTML elements. For these cases, there is the alternative URL Signature Auth.
This mechanism is a simplistic but similar approach to other solutions to access protected resources, such as AWS presigned URLs or Azure shared access signatures (SAS).
With URL Signature Auth, a JSON Web Token (JWT) is generated, wich must be appended to the file URL in the query parameter jwt.
To obtain such a token, you must send a POST request with no body to the following endpoint, using the normal Bearer Login Auth via a token with read scope:
/auth/url_signatures
You will receive a single string with the token.
Append this token to the attachment URLs accordingly. For illustrative purposes only:
<img src="/attachments/UUID.ext?jwt=token" />
At the moment, the same token can be used with any supported attachment file download URL —while is valid.
For security reasons these tokens are short-lived (10 minutes), but you can generate as many as needed.