add validity field to fixtures and tests, update docs

FIXTURES.md

@@ -1,4 +1,5 @@
-id|description|reference
+id|description|valid v1|valid v2
 ---|---|---
-001|A vector tile without any layers, which essentially results in a completely empty buffer. This is invalid according to both the v1 and v2 specifications.|[link](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L75)
-002|A single layer with a single point feature that has no id field. According to the specification, "A feature MAY contain an id field. If a feature has an id field, the value of the id SHOULD be unique among the features of the parent layer."|[link](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/README.md#42-features)
+001|A vector tile without any layers, which essentially results in a completely empty buffer. - [link](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L75)|true|true
+002|A single layer with a single point feature that has no id field. According to the specification, "A feature MAY contain an id field. If a feature has an id field, the value of the id SHOULD be unique among the features of the parent layer." - [link](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/README.md#42-features)|true|true
+003|A single point feature with a missing geometry type. From the spec, "A feature MUST contain a type field as described in the Geometry Types section." - [link](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L41) - recommended error handling `recoverable`|false|false

README.md

@@ -13,6 +13,14 @@ mvt-fixtures can be used in two distinct ways
 
 The Javascript API is recommended if you are working in Javascript or Node.js. The raw fixtures are provided for those using this outside of a Javascript application. The recommended workflow is to have your encoder or decoder loop through every fixture and either expect to successfully decode/encode valid fixtures, or fail to decode/encode invalid fixtures. When new fixtures are added to this repository, you simply need to update the version of the module (or your submodule) to get the new fixtures and re-run tests.
 
+**Validity:** each fixture includes information about whether they are valid according to the specification versions and possible error outcomes if they are invalid. If any of the fixtures are invalid, they must include an `error` field describing how to recover (or not) from the error. These can be found in the `validity` field of the fixture and info.json files. The following checks:
+
+* `v1` (Boolean): is this fixture valid according to Version 1.x of the Mapbox Vector Tile spec
+* `v2` (Boolean): is this fixture valid according to Version 2.x of the Mapbox Vector Tile spec
+* `error` (String): describes if the encoder/decoder should recover from this error or stop completely. Values are
+  * `recoverable`: should the encoder/decoder continue move on and continue its work? For instance, if invalid geometry is found, can the encoder safely move to the next feature?
+  * `fatal`: the encoder should completely stop its process
+
 ### Javascript usage
 
 Check out the full Javascript interface over at [API.md](API.md)

fixtures/001/info.json

@@ -1,4 +1,8 @@
 {
-  "description": "A vector tile without any layers, which essentially results in a completely empty buffer. This is invalid according to both the v1 and v2 specifications.",
-  "specification_reference": "https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L75"
+  "description": "A vector tile without any layers, which essentially results in a completely empty buffer.",
+  "specification_reference": "https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L75",
+  "validity": {
+    "v1": true,
+    "v2": true
+  }
 }

fixtures/002/info.json

@@ -1,4 +1,8 @@
 {
   "description": "A single layer with a single point feature that has no id field. According to the specification, \"A feature MAY contain an id field. If a feature has an id field, the value of the id SHOULD be unique among the features of the parent layer.\"",
-  "specification_reference": "https://github.com/mapbox/vector-tile-spec/blob/master/2.1/README.md#42-features"
+  "specification_reference": "https://github.com/mapbox/vector-tile-spec/blob/master/2.1/README.md#42-features",
+  "validity": {
+    "v1": true,
+    "v2": true
+  }
 }

fixtures/003/info.json

@@ -0,0 +1,9 @@
+{
+  "description": "A single point feature with a missing geometry type. From the spec, \"A feature MUST contain a type field as described in the Geometry Types section.\"",
+  "specification_reference": "https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L41",
+  "validity": {
+    "v1": false,
+    "v2": false,
+    "error": "recoverable"
+  }
+}

fixtures/003/tile.json

@@ -0,0 +1,22 @@
+{
+  "layers": [
+    {
+      "version": 2,
+      "name": "hello",
+      "features": [
+        {
+          "id": 1,
+          "tags": [],
+          "geometry": [
+            9,
+            50,
+            34
+          ]
+        }
+      ],
+      "keys": {},
+      "values": {},
+      "extent": 4096
+    }
+  ]
+}

index.js

@@ -49,6 +49,7 @@ function get(id) {
   final.specification_reference = fixture.specification_reference;
   final.json = fixture.json;
   final.buffer = generateBuffer(fixture.json);
+  final.validity = fixture.validity;
   if (fixture.manipulate) {
     final.buffer = fixture.manipulate(final.buffer);
   }

scripts/build.js

@@ -18,6 +18,7 @@ mvtf.each(function(fixture) {
   fs.writeFileSync(json, JSON.stringify(fixture.json, null, 2));
   fs.writeFileSync(info, JSON.stringify({
     description: fixture.description,
-    specification_reference: fixture.specification_reference
+    specification_reference: fixture.specification_reference,
+    validity: fixture.validity
   }, null, 2));
 });

scripts/docs.js

@@ -3,12 +3,16 @@
 const fs = require('fs');
 const mvtf = require('..');
 
-let docs = `id|description|reference
+let docs = `id|description|valid v1|valid v2
 ---|---|---
 `;
 
 mvtf.each(function(fixture) {
-  docs+=`${fixture.id}|${fixture.description}|[link](${fixture.specification_reference})\n`;
+  let description = `${fixture.description} - [link](${fixture.specification_reference})`;
+  if (!fixture.validity.v1 || !fixture.validity.v2) {
+    description += ` - recommended error handling \`${fixture.validity.error}\``;
+  }
+  docs+=`${fixture.id}|${description}|${fixture.validity.v1}|${fixture.validity.v2}\n`;
 });
 
 fs.writeFileSync('./FIXTURES.md', docs);

scripts/new.js

@@ -6,9 +6,13 @@ const id = getID(files.length + 1); // get the next available number
 
 const template = `module.exports = function(schema) {
   return {
-    name: '${id}',
     description: 'DESCRIPTION',
     specification_reference: 'https://github.com/mapbox/vector-tile-spec/blob/master/2.1/README.md',
+    validity: {
+      v1: true,
+      v2: true,
+      error: 'IF INVALID, ERROR TYPE HERE'
+    },
     json: {
       layers: [
         {

src/001.js

@@ -1,7 +1,11 @@
 module.exports = function(schema) {
   return {
-    description: 'A vector tile without any layers, which essentially results in a completely empty buffer. This is invalid according to both the v1 and v2 specifications.',
+    description: 'A vector tile without any layers, which essentially results in a completely empty buffer.',
     specification_reference: 'https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L75',
+    validity: {
+      v1: true,
+      v2: true
+    },
     json: {}
   }
 };

src/002.js

@@ -2,6 +2,10 @@ module.exports = function(schema) {
   return {
     description: 'A single layer with a single point feature that has no id field. According to the specification, "A feature MAY contain an id field. If a feature has an id field, the value of the id SHOULD be unique among the features of the parent layer."',
     specification_reference: 'https://github.com/mapbox/vector-tile-spec/blob/master/2.1/README.md#42-features',
+    validity: {
+      v1: true,
+      v2: true
+    },
     json: {
       layers: [
         {

src/003.js

@@ -0,0 +1,34 @@
+module.exports = function(schema) {
+  return {
+    description: 'A single point feature with a missing geometry type. From the spec, "A feature MUST contain a type field as described in the Geometry Types section."',
+    specification_reference: 'https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L41',
+    validity: {
+      v1: false,
+      v2: false,
+      error: 'recoverable'
+    },
+    json: {
+      layers: [
+        {
+          version: 2,
+          name: 'hello',
+          features: [
+            {
+              id: 1,
+              tags: [],
+              // type: schema.Tile.GeomType.POINT.value,
+              geometry: [ 9, 50, 34 ]
+            }
+          ],
+          keys: {},
+          values: {},
+          extent: 4096
+        }
+      ]
+    },
+    manipulate: function(buffer) {
+      // stuff here
+      return buffer;
+    }
+  }
+};

test/each.test.js

@@ -14,6 +14,7 @@ test('[each] loads all fixtures', (assert) => {
     assert.ok(fixture.description);
     assert.ok(fixture.buffer);
     assert.ok(fixture.specification_reference);
+    assert.ok(fixture.validity);
   });
 
   assert.equal(numFixtures, count, 'expected number of fixtures');

test/get.test.js

@@ -32,6 +32,8 @@ test('[get] success, gets a fixture and its properties/buffer', (assert) => {
   assert.ok(fixture.json);
   assert.ok(fixture.description);
   assert.ok(fixture.specification_reference);
+  assert.ok(fixture.validity);
+  console.log(fixture.manipulate);
   assert.notOk(fixture.manipulate);
   assert.equal(typeof fixture.buffer, 'object', 'returns a buffer');