Skip to content
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

Jump to bottom

Implement the new extensions model #429

Closed
12 of 16 tasks
danbri opened this issue Apr 16, 2015 · 6 comments
Closed
12 of 16 tasks

Implement the new extensions model #429

danbri opened this issue Apr 16, 2015 · 6 comments
Assignees
@RichardWallis
Labels
site tools + python code Infrastructural issues around schema.org site. Most can ignore this! type:tricky problem Hard problems, including modeling / vocabulary and infrastructural aspects (eg fiction, probability)
Milestone
sdo-ganymede release

Comments

@danbri
Copy link
Contributor

danbri commented Apr 16, 2015

Meta bug. See discussion thread https://lists.w3.org/Archives/Public/public-vocabs/2015Mar/0117.html

Related: draft bib: extension #431 https://lists.w3.org/Archives/Public/public-schemabibex/2015Apr/0000.html

First cut code was merged from sdo-scripts into sdo-gozer, April 27th.

TODOs

Site navigation

For any running installation of the schema.org site, ... considering a base domain such as 'schema.org', 'sdo-gozer.appspot.com', 'webschemas.org' etc., here written BASE_DOMAIN:

  • foo.BASE_DOMAIN/Person (since Person is a term defined in the core, and 'foo' is a hypothetical extension) should display as normal, while indicating that we are viewing the 'foo' extension.
  • xyz.BASE_DOMAIN/Person etc. should completely fail, e.g. 404 or browser resolution error, if 'xyz' is not enabled as an extension name on that installation.
  • foo.BASE_DOMAIN/XyzAbc should fail by 404 if XyzAbc is not a known term in any enabled extension running on that installation.
  • BASE_DOMAIN/Globe should fail with a helpful 404, with links to each extension e.g. 'foo' which defines/mentions the term 'Globe' (or any term that is known to an extension enabled in that installation).
  • foo.BASE_DOMAIN/Globe should succeed, rendering a per-term page describing Globe, assuming Globe is a term defined in an extension 'foo' enabled on that installation. Navigation to related terms from core and from within 'foo' by normal means, i.e. Place, Event, CreativeWork, name etc from core would be listed and navigable "within the extension". STATUS: http://bib.webschemas.org/Globe?ext=bib works but needs the ext=bib still.
  • foo.BASE_DOMAIN/ should present a simple homepage for the extension, including a short description of its purpose/scope, and a link to github for development. It should also list all terms defined by the extension, including their (e.g. supertype, subtype) connection to the core. This assumes content-type requested was text/html.
  • foo.BASE_DOMAIN/docs/datamodel.html and other generic documentation should redirect transparently to BASE_DOMAIN/docs/datamodel.html to avoid proliferation of multiple URLs for the same static content.
  • foo.BASE_DOMAIN/docs/xyz where xyz is jsonldcontext.json.txt, jsonldcontext.json, tree.jsonld, or full.html needs more thought. These are dynamically generated from "the" schema. Should we replicate per extension? Perhaps move them to a separate path e.g. /data/ or /versions/current/ ?
  • foo.BASE_DOMAIN/ when content type requested is 'application/ld+json' should be a JSON-LD context file, however exact form needs consideration.
  • HTML class attributes are set in the when we are in an extension mode, although the default style sheet currently does not make great use of this.
  • BASE_DOMAIN/ for e.g. CreativeWork should have some link (under 'more...', or lower in page below core vocab) to foo.BASE_DOMAIN/Xyz if Xyz is a subtype, supertype, subproperty, superproperty of CreativeWork in an enabled extension 'foo' on this installation. STATUS: http://webschemas.org/CreativeWork has 'mentions' under 'more...', although the cross-links use url params currently.

Data loading and internal APIs

As with schema.org core, all schemas and examples are deployed as part of site updates; they are not loaded dynamically from the Web. This first extensions implementation only addresses reviewed/hosted extensions (e.g. "bib.schema.org") and has no treatment of external extensions, i.e. those on external domains.

  • schema data is read from data/ext/{xyz}/*.rdfa files, loaded schema graphs named as layers 'xyz', 'bib' etc, following the folder names.
  • extension-specific examples should be read from data/ext/{xyz}/*txt files, following the format conventions of core schema.org.
  • Many functions in api.py now take an optional argument (defaulting to 'core') that lists the layer(s) to be applied.
  • There is a notion of current active extension. The default is no extension, i.e. we view only 'the core'. If we are in xyz.BASE_DOMAIN/ then our current active extension is 'xyz'. Current active extension is set by inspecting actual domain and comparing to BASE_DOMAIN.
  • Although there is internal API support (and debugging via URL parameters, ?ext=foo,bar,abc,...), we do not offer public support for navigating multiple extensions simultaneously. Most users will either be looking at a term in the core, a term defined in the extension, or a core term navigated within an extension.

Testing

  • Where BASE_DOMAIN is the webschemas.org installation (using a test domain similar to schema.org for clarity)
  • 'bib' is a work-in-progress (test data only currently) reviewed/hosted extension enabled in this installation, and loaded from data/ext/bib/*rdfa
  • 'Globe' is a term defined in the bib: extension (although the actual bib extension may not eventually define it, the term is useful for testing here...)

Test URLs:

  • http://webschemas.org/Person - core term in core. Expect this to navigate as in classic 'Person' (i.e. schema.org/Person), including some basic discoverability of links into extensions where extension has terms related to Person. STATUS: crude cross-links under 'more...' .
  • http://bib.webschemas.org/Person - core term, viewed from bib extension. Expect classic navigation of Person but with a header telling us this is the the bib extension. Top of page should be 'bib.schema.org' hyperlinked to front page.
  • http://qwertyuiop.webschemas.org/Person - core term, bogus extension subdomain. Expect: failure to load in browser.
  • http://bib.webschemas.org/Globe - a term defined in (this version of) bib: extension, and navigated within Bib extension.
  • http://bib.webschemas.org/ - front page of bib extension. Expect a short intro with links to all or main terms for the extension.
  • http://webschemas.org/Globe - Looking in the core site for a term from an extension, 'Globe', that is not in the core. a 404 or 404-like page, saying that "Globe" is not in the core but listing links to extensions that define or describe it.
@danbri danbri added type:enhancement site tools + python code Infrastructural issues around schema.org site. Most can ignore this! type:tricky problem Hard problems, including modeling / vocabulary and infrastructural aspects (eg fiction, probability) labels Apr 16, 2015
@danbri danbri self-assigned this Apr 16, 2015
@danbri danbri added this to the sdo-gozer release milestone Apr 16, 2015
@danbri danbri mentioned this issue Apr 16, 2015
Closed
8 tasks
@thadguidry
Copy link
Contributor

It would be nice to simply use GitHub (and Git clients) Search to easily find same or similar named properties, types, etc. across core and extensions (to help with aligning extensions and core, etc).

Q: I think putting extensions themselves in a separate parent folder in the repository (instead of under /data ) might help even more with filtering mechanisms (path) in GitHub extensions and Git clients that many of us use ? Although symbolic links and aliases can help on the client side, second thought.

This was referenced Apr 17, 2015
Open
Closed
@danbri
Copy link
Contributor Author

danbri commented Apr 28, 2015

Also Richard Wallis noted we had reverted to poor utf8 behaviour w/ schema loading, need to find/fix that report.

@danbri
Copy link
Contributor Author

danbri commented Apr 29, 2015

In pursuit of the above, I've been wiring in the JINJA2 template engine (#459). The homepage is now composed via script-capable templates from templates/*tpl. The variables exposed to the templates are currently too chaotic and shouldn't be considered a stable API. We can rationalize those naming choices once the thing is in a functioning state.

@danbri danbri modified the milestones: 2015 Q2, sdo-gozer release May 12, 2015
danbri added a commit that referenced this issue May 19, 2015
@danbri
Working on extensions again #429 - added a list of specifically enabl…
afa130b 
…ed extensions.
@RichardWallis RichardWallis mentioned this issue Jul 23, 2015
Merged
RichardWallis pushed a commit that referenced this issue Jul 23, 2015
Updated release notice for #655 and #429
a5ba8d8
@danbri danbri assigned RichardWallis and unassigned danbri Jul 24, 2015
@RichardWallis
Copy link
Contributor

First pass ready for evaluation and comment. 'bib' extension proposal implemented to to view.

Enhancement to rdfa files

New element required for classes and properties to associate them with an extension:
Example from https://github.com/schemaorg/schemaorg/blob/sdo-ganymede/data/ext/bib/bsdo-1.0.rdfa

<div typeof="rdfs:Class" resource="http://schema.org/Chapter">
    <link property="http://schema.org/isPartOf" href="http://bib.schema.org" />
    <span class="h" property="rdfs:label">bib:Chapter</span>
    <span property="rdfs:comment">One of the sections into which a book is divided. A chapter usually has a section number or a name.</span>
    <span> Subclass of:<a property="rdfs:subClassOf" href="http://schema.org/CreativeWork">schema:CreativeWork</a>
    </span>
</div>

Note: The 'http://schema.org/isPartOf' definition is only required for new [across all extensions & core] terms. The default is to be partOf http://schema.org hence it is not required in core rdfa files. It is also not required when adding extension specific details to an already defined term - eg. Adding to the range of a property:

<div typeof="rdf:Property" resource="http://schema.org/pageEnd">
    <span class="h" property="rdfs:label">schema:pageEnd</span>
    <span>Domain:<a property="http://schema.org/domainIncludes" href="http://schema.org/Chapter">bib:Chapter</a></span>
</div>

Display / Navigation of terms in hosted extensions

Home page

Identifying terms from an extension

See example: http://bib.sdo-ganymede.appspot.com/Audiobook

  • Visual clue that a term is defined in an extension -- When in extension display mode terms, that are defined in an extension are displayed with '*' as a suffix.
  • CSS identification of extension defined terms -- A class property indicating the extension type has been added to the for the term to allow future visual identification.
<code property="rdfs:label"><a class="ext-bib" href="/readBy">readBy</a>*</code>

See example: http://bib.sdo-ganymede.appspot.com/Book where abridged property is displayed whereas it is not visible in http://sdo-ganymede.appspot.com/Book

Identifying potential properties from extensions when displaying in core

See example: http://sdo-ganymede.appspot.com/Book

  • Display Available properties in extensions -- On Type display listed near end of information by Type

Navigation to extension definition

  • Clicking on an, extension defined term when in core will take user to that term in the correct extension.
  • When in extension display mode, clicking on a any term defined in core or the currently displayed extension will take the user to that term whilst remaining in the current extension mode.

ToDo

  • When in core, display available superclasses defined in extensions.
  • Extension enhancements to full listing of types eg. List only types defined in an extension, or core only, or all types in core and extensions.

@RichardWallis RichardWallis reopened this Jul 27, 2015
@danbri danbri mentioned this issue Jul 27, 2015
Open
danbri added a commit that referenced this issue Jul 27, 2015
@danbri
Added isPartOf declarations for terms defined in auto extension.
68cc27e 
For #509 #429
RichardWallis pushed a commit that referenced this issue Aug 27, 2015
Redirect (http 301) all calls via sdoapp to www.schema.org to schema.…
4b1e25f 
…org (#727)

Cleaned up navigation after v2.1.
Made navigation through menus and docs consistent as to when to remain in an extension or to force to basic schema.org.  Included making schemas.html into a template.

Also maintains the http/https state through a user session.
Corrected thread based caching of global variables errors that were introduced with extensions - reset temporary fix of threadsafe=false in app.yaml.

Introduced a /_siteDebug page to monitor cache usage and settings etc.

Issues:
(#429) - Completing the initial extensions model
(#732) - Docs links for menus now go to base url
(#716) - Preparing ground by at least being in session consistent
@RichardWallis RichardWallis mentioned this issue Aug 27, 2015
Merged
@RichardWallis
Copy link
Contributor

This can be closed following application of pull (#751)

There will be further enhancements to how user interact with extensions but they should be raised separately.

@danbri
Copy link
Contributor Author

danbri commented Sep 7, 2015

Yup. We should list new things needing extension-related support in #1 too (including external extensions)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@RichardWallis RichardWallis

Labels
site tools + python code Infrastructural issues around schema.org site. Most can ignore this! type:tricky problem Hard problems, including modeling / vocabulary and infrastructural aspects (eg fiction, probability)
Projects
None yet
Milestone
sdo-ganymede release
Development

No branches or pull requests

3 participants
@danbri @thadguidry @RichardWallis