Skip to content

Commit cc50f66

Browse files
jason-foxjason-fox
authored
Add Markdown formatter (FIWARE#312)
* Add linter and formatter for markdown (Fix FIWARE#186) * Format markdown * Run text linter - spellcheck and correct. * Remove whitespace around codeblock fences - (Fix FIWARE#310) After correcting spelling mistakes additional whitespace formatting issues can be corrected.
1 parent be8f0db commit cc50f66

File tree

105 files changed

+9839
-7076
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

105 files changed

+9839
-7076
lines changed

‎README.md

+85-57
Original file line numberDiff line numberDiff line change
@@ -7,35 +7,49 @@
77
[![Build badge](https://img.shields.io/travis/Fiware/dataModels.svg "Travis build status")](https://travis-ci.org/Fiware/dataModels/)
88
[![Support badge](https://img.shields.io/badge/support-askbot-yellowgreen.svg)](http://ask.fiware.org)
99

10-
This repository contains:
11-
* [JSON Schemas and documentation](./specs/README.md) on harmonized datamodels for smart cities, developed jointly with [OASC](http://oascities.org), and other domains.
12-
* code that allows to expose different harmonized datasets useful for different applications.
13-
Such datasets are exposed through the [FIWARE NGSI version 2](http://fiware.github.io/specifications/ngsiv2/stable) API (query).
10+
This repository contains:
11+
12+
- [JSON Schemas and documentation](./specs/README.md) on harmonized datamodels
13+
for smart cities, developed jointly with [OASC](http://oascities.org), and
14+
other domains.
15+
- code that allows to expose different harmonized datasets useful for
16+
different applications. Such datasets are exposed through the
17+
[FIWARE NGSI version 2](http://fiware.github.io/specifications/ngsiv2/stable)
18+
API (query).
1419

1520
This work is aligned with the results of the
1621
[GSMA IoT Big Data](http://www.gsma.com/connectedliving/iot-big-data/) Project.
17-
Such project is working on the harmonization of APIs and data models for fueling IoT and Big Data Ecosystems.
18-
In fact the FIWARE data models are a superset of the [GSMA Data Models](http://www.gsma.com/connectedliving/wp-content/uploads/2016/11/CLP.26-v1.0.pdf).
22+
Such project is working on the harmonization of APIs and data models for fueling
23+
IoT and Big Data Ecosystems. In fact the FIWARE data models are a superset of
24+
the
25+
[GSMA Data Models](http://www.gsma.com/connectedliving/wp-content/uploads/2016/11/CLP.26-v1.0.pdf).
1926

20-
All the code in this repository is licensed under the MIT License. However each original data source may have a different license.
21-
So before using harmonized data please check carefully each data license.
27+
All the code in this repository is licensed under the MIT License. However each
28+
original data source may have a different license. So before using harmonized
29+
data please check carefully each data license.
2230

23-
All the data models documented here are offered under a [Creative Commons by Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) License.
31+
All the data models documented here are offered under a
32+
[Creative Commons by Attribution 4.0](https://creativecommons.org/licenses/by/4.0/)
33+
License.
2434

2535
## Data Models adoption
2636

27-
To support the adoption, we created a short [guideline](specs/howto.md)
28-
for the usage of data models.
37+
To support the adoption, we created a short [guideline](specs/howto.md) for the
38+
usage of data models.
2939

3040
## JSON Schemas
3141

32-
We intend to provide a [JSON Schema](http://json-schema.org/) for every harmonized data model. In the future all the
33-
documentation could be generated from a JSON Schema, as it is part of our roadmap. The different JSON Schemas usually
34-
depend on common JSON Schema definitions found at the root directory of this repository.
42+
We intend to provide a [JSON Schema](http://json-schema.org/) for every
43+
harmonized data model. In the future all the documentation could be generated
44+
from a JSON Schema, as it is part of our roadmap. The different JSON Schemas
45+
usually depend on common JSON Schema definitions found at the root directory of
46+
this repository.
3547

36-
There are different online JSON Schema Validators, for instance: [http://jsonschemalint.com/](http://jsonschemalint.com/).
37-
For the development of these schemas the [AJV JSON Schema Validator](https://github.com/epoberezkin/ajv) is being used. For
38-
using it just install it through npm:
48+
There are different online JSON Schema Validators, for instance:
49+
[http://jsonschemalint.com/](http://jsonschemalint.com/). For the development of
50+
these schemas the
51+
[AJV JSON Schema Validator](https://github.com/epoberezkin/ajv) is being used.
52+
For using it just install it through npm:
3953

4054
```
4155
npm install ajv
@@ -44,47 +58,61 @@ using it just install it through npm:
4458

4559
A `validate.sh` script is provided for convenience.
4660

47-
**Note**: JSON Schemas only capture the NGSI simplified representation, this means that to test the JSON schema examples with
48-
a [FIWARE NGSI version 2](http://fiware.github.io/specifications/ngsiv2/stable) API implementation, you need to use the `keyValues`
49-
mode (`options=keyValues`).
61+
**Note**: JSON Schemas only capture the NGSI simplified representation, this
62+
means that to test the JSON schema examples with a
63+
[FIWARE NGSI version 2](http://fiware.github.io/specifications/ngsiv2/stable)
64+
API implementation, you need to use the `keyValues` mode (`options=keyValues`).
5065

5166
## How to contribute
5267

53-
Contributions should come in the form of pull requests.
68+
Contributions should come in the form of pull requests.
5469

5570
New data models should be added under a folder structured as follows:
56-
- `specs/`
57-
- `NewModel/`
58-
- `doc/`
59-
- `spec.md`: A data model description based on the [data model template](datamodel_template.md), e.g. [spec.md of WeatherObserved](specs/Weather/WeatherObserved/doc/spec.md).
60-
- `README.md`: A summary file (as an extract from the spec file), e.g. [README.md of WeatherObserved](specs/Weather/WeatherObserved/README.md)
61-
- `schema.json`: The JSON Schema definition, e.g. [schema.json of WeatherObserved](specs/Weather/WeatherObserved/schema.json)
62-
- `example.json`: One or more JSON example file, e.g. [example.json of WeatherObserved](specs/Weather/WeatherObserved/example.json)
63-
64-
The name of the folder should match the entity type used in the JSON Schema (e.g. `NewModel`). For data models including more entities, a hierarchical folder should be used. The father folder can include common JSON schemas shared among the entities. e.g.:
65-
66-
- `specs/`
67-
- `NewModel/`
68-
- `doc/`
69-
- `spec.md`
70-
- `README.md`
71-
- `newmodel-schema.json`: the common schema for the different entities.
72-
- `NewModelEntityOne/`
73-
- `doc/`
74-
- `spec.md`
75-
- `README.md`
76-
- `schema.json`
77-
- `example.json`
78-
- `NewModelEntityTwo/`
79-
- `doc/`
80-
- `spec.md`
81-
- `README.md`
82-
- `schema.json`
83-
- `example.json`
84-
85-
To facilitate contributions and their validation, we developed a tool that is also used for the Continuous Integration of FIWARE Data Models. The FIWARE Data Model validator checks the adherence of each data model to the [FIWARE Data Models guidelines](specs/guidelines.md).
86-
87-
For using it just install it through npm:
71+
72+
- `specs/`
73+
- `NewModel/`
74+
- `doc/`
75+
- `spec.md`: A data model description based on the
76+
[data model template](datamodel_template.md), e.g.
77+
[spec.md of WeatherObserved](specs/Weather/WeatherObserved/doc/spec.md).
78+
- `README.md`: A summary file (as an extract from the spec file), e.g.
79+
[README.md of WeatherObserved](specs/Weather/WeatherObserved/README.md)
80+
- `schema.json`: The JSON Schema definition, e.g.
81+
[schema.json of WeatherObserved](specs/Weather/WeatherObserved/schema.json)
82+
- `example.json`: One or more JSON example file, e.g.
83+
[example.json of WeatherObserved](specs/Weather/WeatherObserved/example.json)
84+
85+
The name of the folder should match the entity type used in the JSON Schema
86+
(e.g. `NewModel`). For data models including more entities, a hierarchical
87+
folder should be used. The father folder can include common JSON schemas shared
88+
among the entities. e.g.:
89+
90+
- `specs/`
91+
- `NewModel/`
92+
- `doc/`
93+
- `spec.md`
94+
- `README.md`
95+
- `newmodel-schema.json`: the common schema for the different
96+
entities.
97+
- `NewModelEntityOne/`
98+
- `doc/`
99+
- `spec.md`
100+
- `README.md`
101+
- `schema.json`
102+
- `example.json`
103+
- `NewModelEntityTwo/`
104+
- `doc/`
105+
- `spec.md`
106+
- `README.md`
107+
- `schema.json`
108+
- `example.json`
109+
110+
To facilitate contributions and their validation, we developed a tool that is
111+
also used for the Continuous Integration of FIWARE Data Models. The FIWARE Data
112+
Model validator checks the adherence of each data model to the
113+
[FIWARE Data Models guidelines](specs/guidelines.md).
114+
115+
For using it just install it through npm:
88116

89117
```
90118
npm install -g fiware-model-validator
@@ -95,10 +123,10 @@ More details are available in the [validator documentation](validator).
95123
[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
96124
[license-url]: LICENSE
97125

98-
## Related Projects
126+
## Related Projects
99127

100128
See:
101129

102-
* [https://github.com/GSMADeveloper/HarmonisedEntityDefinitions](https://github.com/GSMADeveloper/HarmonisedEntityDefinitions)
103-
* [https://github.com/GSMADeveloper/HarmonisedEntityReferences](https://github.com/GSMADeveloper/HarmonisedEntityReferences)
104-
* [schema.org](https://schema.org)
130+
- [https://github.com/GSMADeveloper/HarmonisedEntityDefinitions](https://github.com/GSMADeveloper/HarmonisedEntityDefinitions)
131+
- [https://github.com/GSMADeveloper/HarmonisedEntityReferences](https://github.com/GSMADeveloper/HarmonisedEntityReferences)
132+
- [schema.org](https://schema.org)

‎datamodel_template.md

+36-30
Original file line numberDiff line numberDiff line change
@@ -6,52 +6,58 @@
66

77
## Data Model
88

9-
A JSON Schema corresponding to this data model can be found {{add link to JSON Schema}}
9+
A JSON Schema corresponding to this data model can be found
10+
{{add link to JSON Schema}}
1011

11-
+ `id` : Unique identifier.
12+
- `id` : Unique identifier.
1213

13-
+ `type` : Entity type. It must be equal to {{EntityType}}.
14+
- `type` : Entity type. It must be equal to {{EntityType}}.
1415

15-
+ `dateModified` : Last update timestamp of this entity.
16-
+ Attribute type: [DateTime](https://schema.org/DateTime)
17-
+ Read-Only. Automatically generated.
16+
- `dateModified` : Last update timestamp of this entity.
1817

19-
+ `dateCreated` : Entity's creation timestamp.
20-
+ Attribute type: [DateTime](https://schema.org/DateTime)
21-
+ Read-Only. Automatically generated.
18+
- Attribute type: [DateTime](https://schema.org/DateTime)
19+
- Read-Only. Automatically generated.
2220

23-
+ `owner` : Entity's owners.
24-
+ Attribute type: List of references to [Person]( http://schema.org/Person) or [Organization](https://schema.org/Organization).
25-
+ Optional
21+
- `dateCreated` : Entity's creation timestamp.
22+
23+
- Attribute type: [DateTime](https://schema.org/DateTime)
24+
- Read-Only. Automatically generated.
25+
26+
- `owner` : Entity's owners.
27+
- Attribute type: List of references to [Person](http://schema.org/Person)
28+
or [Organization](https://schema.org/Organization).
29+
- Optional
2630

2731
{{Location and address are two typical attributes that are added here for convenience}}
2832

29-
+ `location` : Location of {{entity type}} represented by a GeoJSON geometry.
30-
+ Attribute type: `geo:json`.
31-
+ Normative References: [https://tools.ietf.org/html/rfc7946](https://tools.ietf.org/html/rfc7946)
32-
+ Mandatory if `address` is not defined.
33-
34-
+ `address` : Civic address of {{entity type}}
35-
+ Normative References: [https://schema.org/address](https://schema.org/address)
36-
+ Mandatory if `location` is not present.
33+
- `location` : Location of {{entity type}} represented by a GeoJSON geometry.
34+
- Attribute type: `geo:json`.
35+
- Normative References:
36+
[https://tools.ietf.org/html/rfc7946](https://tools.ietf.org/html/rfc7946)
37+
- Mandatory if `address` is not defined.
38+
- `address` : Civic address of {{entity type}}
39+
- Normative References:
40+
[https://schema.org/address](https://schema.org/address)
41+
- Mandatory if `location` is not present.
3742

3843
{{Below there is a description of a typical attribute}}
3944

40-
+ `{{attributeName}}` : {{Description of the attribute}}
41-
+ Normative References: {{Add a normative reference}}
42-
+ Attribute type: {{Add here the attribute type}}
43-
+ Attribute metadata:
44-
+ `{{metadata name}}` : {{Metadata Description}}
45-
+ {{Optional/Mandatory}}
45+
- `{{attributeName}}` : {{Description of the attribute}}
46+
- Normative References: {{Add a normative reference}}
47+
- Attribute type: {{Add here the attribute type}}
48+
- Attribute metadata:
49+
- `{{metadata name}}` : {{Metadata Description}}
50+
- {{Optional/Mandatory}}
4651

47-
**Note**: JSON Schemas only capture the NGSI simplified representation, this means that to test the JSON schema examples with
48-
a [FIWARE NGSI version 2](http://fiware.github.io/specifications/ngsiv2/stable) API implementation, you need to use the `keyValues`
49-
mode (`options=keyValues`).
52+
**Note**: JSON Schemas only capture the NGSI simplified representation, this
53+
means that to test the JSON schema examples with a
54+
[FIWARE NGSI version 2](http://fiware.github.io/specifications/ngsiv2/stable)
55+
API implementation, you need to use the `keyValues` mode (`options=keyValues`).
5056

5157
## Examples of use
5258

5359
{{Provide a JSON example}}
54-
60+
5561
## Use it with a real service
5662

5763
{{Provide a link to a real service providing data following the harmonized data format}}

‎specs/Alert/README.md

+16-8
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,25 @@
11
# Alert data model
22

33
## Description
4-
This entity models an alert and could be used to send alerts related to traffic jam, accidents, weather conditions, high level of pollutants and so on.
5-
The purpose of the model is to support the generation of notifications for a user or trigger other actions,
6-
based on such alerts.
74

8-
An alert is generated by a specific situation. The main features of an alert is that it is not predictable and it is not a recurrent data. That means that an alert could be an accident or a high level of pollutants measure, additionally it could be the fall down of a patient or a car driving in the opposite direction.
5+
This entity models an alert and could be used to send alerts related to traffic
6+
jam, accidents, weather conditions, high level of pollutants and so on. The
7+
purpose of the model is to support the generation of notifications for a user or
8+
trigger other actions, based on such alerts.
99

10-
Some examples of context data are: type of alert (traffic, suspicious activities, and pollution, etc.), severity, location and so on.
10+
An alert is generated by a specific situation. The main features of an alert is
11+
that it is not predictable and it is not a recurrent data. That means that an
12+
alert could be an accident or a high level of pollutants measure, additionally
13+
it could be the fall down of a patient or a car driving in the opposite
14+
direction.
1115

12-
**Note**: JSON Schemas only capture the NGSI simplified representation, this means that to test the JSON schema examples with
13-
a [FIWARE NGSI version 2](http://fiware.github.io/specifications/ngsiv2/stable) API implementation, you need to use the `keyValues`
14-
mode (`options=keyValues`).
16+
Some examples of context data are: type of alert (traffic, suspicious
17+
activities, and pollution, etc.), severity, location and so on.
18+
19+
**Note**: JSON Schemas only capture the NGSI simplified representation, this
20+
means that to test the JSON schema examples with a
21+
[FIWARE NGSI version 2](http://fiware.github.io/specifications/ngsiv2/stable)
22+
API implementation, you need to use the `keyValues` mode (`options=keyValues`).
1523

1624
## Examples of use
1725

0 commit comments

Comments
 (0)