Improve documentation. Add feature of skipping some inner scopes.

Author: Peter Amstutz

schema_salad/metaschema/metaschema.yml

@@ -144,12 +144,18 @@ $graph:
         - "null"
         - int
       doc: |
-        Remove the specified number of layers from the containing identifer
-        scope and join with the field value to yield the identifier.  For
-        example, an identifer scope of `#foo/bar/baz`, `refScope: 0` and
-        identifier `quux` will yield `#foo/bar/baz/quux`.  `refScope: 1` will
-        yield `#foo/bar/quux`, `refScope: 2` will yield `#foo/quux` and so
-        forth.
+        If the field contains a relative reference, it must be resolved by
+        searching for valid document references in each successive parent scope
+        in the document fragment.  For example, a reference of `foo` in the
+        context `#foo/bar/baz` will first check for the existence of
+        `#foo/bar/baz/foo`, followed by `#foo/bar/foo`, then `#foo/foo` and
+        then finally `#foo`.  The first valid URI in the search order shall be
+        used as the fully resolved value of the identifier.  The value of the
+        refScope field is the specified number of levels from the containing
+        identifer scope before starting the search, so if `refScope: 2` then
+        "baz" and "bar" must be stripped to get the base `#foo` and search
+        `#foo/foo` and the `#foo`.  The last scope searched must be the top
+        level scope before determining if the identifier cannot be resolved.
 
 - name: SpecializeDef
   type: record

schema_salad/ref_resolver.py

@@ -208,7 +208,7 @@ def add_context(self, newcontext, baseuri=""):
                 self.identity_links.add(key)
             elif isinstance(value, dict) and value.get("@type") == "@id":
                 self.url_fields.add(key)
-                if value.get("refScope", False):
+                if "refScope" in value:
                     self.scoped_ref_fields[key] = value["refScope"]
                 if value.get("identity", False):
                     self.identity_links.add(key)
@@ -548,16 +548,14 @@ def validate_link(self, field, link, docid):
                 if field in self.scoped_ref_fields:
                     split = urlparse.urlsplit(docid)
                     sp = split.fragment.split("/")
-                    print field, self.scoped_ref_fields[field], sp
-                    if self.scoped_ref_fields[field] in ("grandparent"):
-                        sp.pop()
-                    if self.scoped_ref_fields[field] in ("parent", "grandparent"):
+                    n = self.scoped_ref_fields[field]
+                    while n > 0 and len(sp) > 0:
                         sp.pop()
+                        n -= 1
                     while True:
                         sp.append(str(link))
                         url = urlparse.urlunsplit(
                             (split.scheme, split.netloc, split.path, split.query, "/".join(sp)))
-                        print "trying", url, "field", field
                         if url in self.idx:
                             return url
                         sp.pop()

tests/test_examples.py

@@ -129,6 +129,9 @@ def test_scoped_ref(self):
                 "mapSubject": "id",
                 "mapPredicate": "type"
             },
+            "outputs": {
+                "mapSubject": "id",
+            },
             "steps": {
                 "mapSubject": "id"
             },
@@ -138,6 +141,12 @@ def test_scoped_ref(self):
             "inputs": {
                 "inp": "string"
             },
+            "outputs": {
+                "out": {
+                    "type": "string",
+                    "source": "step2/out"
+                }
+            },
             "steps": {
                 "step1": {
                     "in": {
@@ -150,17 +159,22 @@ def test_scoped_ref(self):
                     "in": {
                         "inp": "step1/out"
                     },
-                    "scatter": "inp"
+                    "scatter": "inp",
+                    "out": ["out"]
                 }
             }
         }, "http://example2.com/")
 
-        print yaml.dump(ra)
-
-        self.assertEquals({'inputs': [{
+        self.assertEquals(
+            {'inputs': [{
                 'id': 'http://example2.com/#inp',
                 'type': 'string'
             }],
+             'outputs': [{
+                'id': 'http://example2.com/#out',
+                 'type': 'string',
+                 'source': 'http://example2.com/#step2/out'
+             }],
             'steps': [{
                     'id': 'http://example2.com/#step1',
                     'scatter': 'http://example2.com/#step1/inp',
@@ -175,7 +189,8 @@ def test_scoped_ref(self):
                     'in': [{
                             'id': 'http://example2.com/#step2/inp',
                             'source': 'http://example2.com/#step1/out'
-                    }]
+                    }],
+                    "out": ["http://example2.com/#step2/out"],
                 }]
         }, ra)