Skip to content

CSV Design Documentaiton #1551

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
krowvin wants to merge 1 commit into
base: develop
Choose a base branch
from
+71 −0
Open

CSV Design Documentaiton #1551

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions docs/source/decisions/0005-comma-separated-values.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
Statement
=========

Continue to allow Comma Separated Values (CSV) and JavaScript Object Notation (JSON) as formats going forward. CWMS Data API (CDA) will officially
support JSON and CSV. Additional formats may be introduced via versioned
changes or explicit content negotiation if a documented use case arises.

Purpose / Need
==============

CSV
---

CSV, without a viewing software, is also highly viewable by humans compared to
JSON.

CSV isolates tabular datasets and minimizes structural overhead, making it
easier to inspect in spreadsheet-oriented workflows. It is easily imported
into various end-user client software (MS Excel/Sheets), and does not require
extra code on the client in order to convert from one format to another when
JSON is the only option.

if end-users wanted to easily manipulate data without first needing to parse it in JSON they would
be able to do so with CSV.

Example: Sharing a link to a specific dataset. This can be handled via a direct
CDA link that when clicked, downloads the CSV file directly.

*Relies on*: ``Content-Type: text/csv`` being set by default.

JSON
----

JSON is the default response format. Some legacy endpoints currently return XML
due to upstream constraints; these are considered transitional and should be
normalized where feasible.

It works well with downstream programming needs and offers additional metadata
beyond what CSV provides.

Expectations
============

1. Query parameter (``?format=``) overrides ``Accept`` header to support browser
downloading via URI control.

- If neither is present, default to JSON.

2. CSV must only include the headers and data fields. No additional metadata, text, or comments at
the top.

- UTF-8 encoded
- Empty values **must** return empty fields, **not** ``null``.
Example: ``date,4.0,,`` **not** ``date,4.0,null,null``
This ensures smaller file sizes and compatibility with common CSV parsers.

3. If data response types must change, such as headers or key-value pairs in a
response, the version **must** be updated to reflect this in the
``Accept`` header to match the practices already in place for versioning. See :doc:`Versioning policy <./0004-data-versioning.rst>` for details.


4. Error handling requirements:

Proper errors must be returned when a format fails to parse (e.g. invalid JSON or a CSV file that does not contain any data or fails to render).

- ``400 Bad Request`` MUST be returned for malformed or invalid client input
- ``415 Unsupported Media Type`` MUST be returned when the requested format is
recognized but not supported for the endpoint
- ``406 Not Acceptable`` MUST be returned when the requested media type will
never be supported by the endpoint
1 change: 1 addition & 0 deletions docs/source/decisions/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,4 @@ Some decisions may also be a proposal and marked appropriately.
Data Versioning <./0002-data-versioning.rst> (rejected, remains for historical context.)
Catalogs and Search <./0003-searchability-and-catalogs.rst>
Versioning <./0004-versioning.rst>
Comma Separated Values <./0005-comma-separated-values.rst>
Loading