Skip to content

Commit

Permalink
Merge pull request #44 from PoseiDAT/feature/vessel-registration
Browse files Browse the repository at this point in the history
Vessel registration entry support
  • Loading branch information
Qwerios authored Dec 1, 2024
2 parents 8af0b43 + 304c6d1 commit 2fb2fa5
Show file tree
Hide file tree
Showing 22 changed files with 8,714 additions and 13,315 deletions.
2 changes: 1 addition & 1 deletion .nvmrc
Original file line number Diff line number Diff line change
@@ -1 +1 @@
v14
v22
17 changes: 14 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ On the other end of the spectrum organizations such as [ICES](http://www.ices.dk
These surveys are more focussed on a certain subject and may not have enough relational markers for commercial business analysis.

The PoseiDAT initiative was created to create something we call the `vessel journal`.
This is the super set of data that brings together all the data collected during a vessels lifetime.
This is the super set of data that brings together all the data collected during a vessels lifetime (or specific ownership period).
A journal is comprised of `entries` that can be sent and collected piecemeal.
An entry is time based log which can contain one or more `events`.
The addition of entries can occur both on board a vessel and at a central land based location by the commercial entity running the vessel.
Expand Down Expand Up @@ -54,6 +54,7 @@ An entry should at least contains the following:
We currently support the following entry types:

* EquipmentInventory (1)
* VesselRegistration (1)
* ServiceHistory (1...n)
* PersonalRoster (1)
* Events (1...n)
Expand All @@ -63,14 +64,22 @@ We currently support the following entry types:
There should only be 1 `EquipmentInventory` which will be updated with new revisions when equipment is installed, replaced or decommissioned.
Since `equipment` can be referenced by event entries (for sensory data) they should never be removed but marked with a status (installed, replaced, etc).

### VesselRegistration

There should only be 1 `VesselRegistration` which will be updated with new revisions when vessel registration details are updated.

### ServiceHistory

> Not implemented yet
Every time vessel or equipment maintenance is carried out a `ServiceHistory` entry should be added to the journal.
The service entry will reference any equipment and/or devices involved and who performed the work.
This entry can also be used to mark the next maintenance interval (if applicable).

### PersonalRoster

> Not implemented yet
The person roster details the current human beings involved with the vessel in some capacity.
Involvement could be anything from captain to passenger.
There should only be 1 `PersonalRoster` which will be updated with new revisions when a persons involvement changes.
Expand Down Expand Up @@ -110,7 +119,9 @@ So even though a new revision can be made the original entry is not modified but
### Archiving entries

Because of the append only nature of the journal removing entries is not supported.
There is however an `archived` flag present which marks an entry as obsolete.
There is however an `archived` flag present in journal server implementations which marks an entry as obsolete.
Note that this is not a property in the entry schema itself but should be a characteristic of the storage system (database) of the entries.
Archiving an entry does not alter the original entry data itself because of append only nature of journal entries.
When exporting data to external systems these archived entries can be skipped.
However for journal integrity and auditing purposes no information should be deleted.

Expand All @@ -128,7 +139,7 @@ These will evolve as the project continues.
* Identifiers should be UUID v4
* Entities should never be copied but referenced by identifier (ex. source device details for a measurement event)
* Any referenced identifier may never be removed/archived from the journal (referential integrity)
* A journal is unique to a vessel (registration changes make it a new vessel)
* A journal is unique to a vessel (vessel ownership changes may warrant a new journal for the same vessel)

## Development

Expand Down
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,8 @@

* [Vessel partner](./vessel-partner.md "Fishing vessel details for partnered fishing")`https://poseidat.org/schema/core/vessel-partner.json`

* [Vessel registration](./vessel-registration.md "An entry detailing the registered details of a vessel like hull number, flag state, etc")`https://poseidat.org/schema/entry/vessel-registration.json`

* [Vessel section](./vessel-section.md "A section off a vessel, used to detail where objects are on the vessel")`https://poseidat.org/schema/core/vessel-section.json`

* [Weather](./weather.md "A combination of all posible weather station measurements")`https://poseidat.org/schema/core/measurement/weather.json`
Expand Down
2 changes: 1 addition & 1 deletion docs/equipment-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
https://poseidat.org/schema/entry/equipment-inventory.json
```

An entry detailing the equipment installed on a vessel. One 1 should exist per journal
An entry detailing the equipment installed on a vessel. Only 1 should exist per journal

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | Defined In |
| :------------------ | :--------- | :------------- | :----------- | :---------------- | :-------------------- | :------------------ | :---------------------------------------------------------------------------------------- |
Expand Down
14 changes: 7 additions & 7 deletions docs/journal.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ A trip journal

# Journal Properties

| Property | Type | Required | Nullable | Defined by |
| :------------------------ | :------- | :------- | :------------- | :----------------------------------------------------------------------------------------------------------------- |
| [journal_id](#journal_id) | `string` | Required | cannot be null | [Journal](journal-properties-journal_id.md "https://poseidat.org/schema/core/journal.json#/properties/journal_id") |
| [vessel](#vessel) | `object` | Required | cannot be null | [Journal](journal-properties-vessel.md "https://poseidat.org/schema/core/vessel.json#/properties/vessel") |
| Property | Type | Required | Nullable | Defined by |
| :------------------------ | :------- | :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------- |
| [journal_id](#journal_id) | `string` | Required | cannot be null | [Journal](journal-properties-journal_id.md "https://poseidat.org/schema/core/journal.json#/properties/journal_id") |
| [vessel](#vessel) | `object` | Required | cannot be null | [Journal](vessel-registration-properties-vessel.md "https://poseidat.org/schema/core/vessel.json#/properties/vessel") |

## journal_id

Expand Down Expand Up @@ -51,12 +51,12 @@ The vessel information

* is required

* Type: `object` ([Vessel](journal-properties-vessel.md))
* Type: `object` ([Vessel](vessel-registration-properties-vessel.md))

* cannot be null

* defined in: [Journal](journal-properties-vessel.md "https://poseidat.org/schema/core/vessel.json#/properties/vessel")
* defined in: [Journal](vessel-registration-properties-vessel.md "https://poseidat.org/schema/core/vessel.json#/properties/vessel")

### vessel Type

`object` ([Vessel](journal-properties-vessel.md))
`object` ([Vessel](vessel-registration-properties-vessel.md))
2 changes: 1 addition & 1 deletion docs/schemas/core/vessel.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://poseidat.org/schema/core/vessel.json","title":"Vessel","description":"The vessel information","properties":{"name":{"type":"string","description":"The display name for the vessel"},"flag_state":{"type":"string","description":"The vessels flag state and country to report ERS messages to. Should be a 3 letter ISO code."},"cfr":{"type":"string","description":"The vessel's Community Fleet Registration number. Fixed format defined by the pattern: \"AAAXXXXXXXXX\" (AAA = Fully capitalised country code of the vessel's first registration within the EU, XXXXXXXXX = 9 character alphanumeric code.). Known as CFR or IR"},"call_sign":{"type":"string","description":"The vessels international radio call sign (RC)"},"hull_number":{"type":"string","description":"The vessel's side (hull) registration number. Also known as XR or PLN. May contain dots or dashes"},"gbr_rss":{"type":"string","description":"GBR ONLY: The vessel's unique identity number as recorded by the UK Registrar of Seamen and Shipping"},"iccat":{"type":"string","description":"International Commission for the Conservation of Atlantic Tuna identifier"},"gfcm":{"type":"string","description":"Global Fisheries Council of the Mediterranean identifier"},"uvi":{"type":"string","description":"Unique Vessel Identifier (IMO number). A number issued by the tuna RFMOs or by ISSF."},"imo_code":{"type":"string","description":"The unique identification of a vessel according to Lloyds register"},"net_tonnage":{"type":"number","description":"The net loading capacity of the vessel, expressed in tons"},"gross_tonnage":{"type":"number","description":"The gross loading capacity of the vessel, expressed in tons"},"registration_date":{"type":"string","format":"date","description":"The date the vessel was registered"},"full_length":{"type":"number","description":"The full length of the vessel in meters"}},"required":["name","cfr","hull_number","flag_state"],"type":"object","additionalProperties":false}
{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://poseidat.org/schema/core/vessel.json","title":"Vessel","description":"The vessel information","properties":{"name":{"type":"string","description":"The display name for the vessel"},"flag_state":{"type":"string","description":"The vessels flag state and country to report ERS messages to. Should be a 3 letter ISO code."},"cfr":{"type":"string","description":"The vessel's Community Fleet Registration number. Fixed format defined by the pattern: \"AAAXXXXXXXXX\" (AAA = Fully capitalised country code of the vessel's first registration within the EU, XXXXXXXXX = 9 character alphanumeric code.). Known as CFR or IR"},"call_sign":{"type":"string","description":"The vessels international radio call sign (RC)"},"hull_number":{"type":"string","description":"The vessel's side (hull) registration number. Also known as XR or PLN. May contain dots or dashes"},"gbr_rss":{"type":"string","description":"GBR ONLY: The vessel's unique identity number as recorded by the UK Registrar of Seamen and Shipping"},"iccat":{"type":"string","description":"International Commission for the Conservation of Atlantic Tuna identifier"},"gfcm":{"type":"string","description":"Global Fisheries Council of the Mediterranean identifier"},"uvi":{"type":"string","description":"Unique Vessel Identifier (IMO number). A number issued by the tuna RFMOs or by ISSF."},"imo_code":{"type":"string","description":"The unique identification of a vessel according to Lloyds register"},"net_tonnage":{"type":"number","description":"The net loading capacity of the vessel, expressed in tons"},"gross_tonnage":{"type":"number","description":"The gross loading capacity of the vessel, expressed in tons"},"registration_date":{"type":"string","format":"date","description":"The date the vessel was registered"},"full_length":{"type":"number","description":"The full length of the vessel in meters"}},"required":["name","hull_number","flag_state"],"type":"object","additionalProperties":false}
2 changes: 1 addition & 1 deletion docs/schemas/entry/equipment-inventory.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://poseidat.org/schema/entry/equipment-inventory.json","title":"Equipment inventory","description":"An entry detailing the equipment installed on a vessel. One 1 should exist per journal","properties":{"entry_type":{"description":"The journal entry type identifier","type":"string","enum":["equipment-inventory"],"default":"equipment-inventory"},"equipment":{"type":"array","description":"The collection of equipment for the vessel","title":"Equipment on board","items":{"$ref":"https://poseidat.org/schema/core/equipment/equipment.json"},"minItems":1,"uniqueItems":true}},"required":["entry_type","equipment"],"allOf":[{"$ref":"https://poseidat.org/schema/core/base-entry.json"}],"type":"object","additionalProperties":true}
{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://poseidat.org/schema/entry/equipment-inventory.json","title":"Equipment inventory","description":"An entry detailing the equipment installed on a vessel. Only 1 should exist per journal","properties":{"entry_type":{"description":"The journal entry type identifier","type":"string","enum":["equipment-inventory"],"default":"equipment-inventory"},"equipment":{"type":"array","description":"The collection of equipment for the vessel","title":"Equipment on board","items":{"$ref":"https://poseidat.org/schema/core/equipment/equipment.json"},"minItems":1,"uniqueItems":true}},"required":["entry_type","equipment"],"allOf":[{"$ref":"https://poseidat.org/schema/core/base-entry.json"}],"type":"object","additionalProperties":true}
1 change: 1 addition & 0 deletions docs/schemas/entry/vessel-registration.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://poseidat.org/schema/entry/vessel-registration.json","title":"Vessel registration","description":"An entry detailing the registered details of a vessel like hull number, flag state, etc. Only 1 should exist per journal","properties":{"entry_type":{"description":"The journal entry type identifier","type":"string","enum":["vessel-registration"],"default":"vessel-registration"},"vessel":{"$ref":"https://poseidat.org/schema/core/vessel.json","title":"The details of the vessel the journal is for"}},"required":["entry_type","vessel"],"allOf":[{"$ref":"https://poseidat.org/schema/core/base-entry.json"}],"type":"object","additionalProperties":true}
31 changes: 31 additions & 0 deletions docs/vessel-registration-properties-entry_type.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Untitled string in Vessel registration Schema

```txt
https://poseidat.org/schema/entry/vessel-registration.json#/properties/entry_type
```

The journal entry type identifier

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Access Restrictions | Defined In |
| :------------------ | :--------- | :------------- | :---------------------- | :---------------- | :-------------------- | :------------------ | :----------------------------------------------------------------------------------------- |
| Can be instantiated | No | Unknown status | Unknown identifiability | Forbidden | Allowed | none | [vessel-registration.json*](schemas/entry/vessel-registration.json "open original schema") |

## entry_type Type

`string`

## entry_type Constraints

**enum**: the value of this property must be equal to one of the following values:

| Value | Explanation |
| :---------------------- | :---------- |
| `"vessel-registration"` | |

## entry_type Default Value

The default value is:

```json
"vessel-registration"
```
Loading

0 comments on commit 2fb2fa5

Please sign in to comment.