From b09f85a5697dd6967bd6ddd9122391f91d587024 Mon Sep 17 00:00:00 2001 From: Seth Shaw Date: Wed, 26 Jun 2019 13:56:05 -0700 Subject: [PATCH 1/2] de-clawing --- CONTRIBUTING.md | 4 +- .../islandora/drupal-bundle-configurations.md | 6 +-- docs/islandora/rdf-mapping.md | 16 +++---- docs/mvp/mvp_doc.md | 8 ++-- .../technical-documentation/drupal-project.md | 4 +- docs/technical-documentation/versioning.md | 2 +- docs/user-documentation/CLAWfor1x.md | 44 ------------------- docs/user-documentation/content_types.md | 2 +- docs/user-documentation/different_from_7x.md | 44 +++++++++++++++++++ ...claw.md => intro-to-ld-for-islandora-8.md} | 10 ++--- 10 files changed, 69 insertions(+), 71 deletions(-) delete mode 100644 docs/user-documentation/CLAWfor1x.md create mode 100644 docs/user-documentation/different_from_7x.md rename docs/user-documentation/{intro-to-ld-for-claw.md => intro-to-ld-for-islandora-8.md} (89%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2ef771e3..26060539d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Welcome! -If you are reading this document then you are interested in contributing to Islandora CLAW. All contributions are welcome: use-cases, documentation, code, patches, bug reports, feature requests, etc. You do not need to be a programmer to speak up! +If you are reading this document then you are interested in contributing to Islandora 8. All contributions are welcome: use-cases, documentation, code, patches, bug reports, feature requests, etc. You do not need to be a programmer to speak up! ## Workflows @@ -8,7 +8,7 @@ The group meets each Wednesday at 1:00 PM Eastern. Meeting notes and announcemen ### Use cases -If you would like to submit a use case to the Islandora CLAW project, please submit an issue [here](https://github.com/Islandora-CLAW/CLAW/issues/new) using the [Use Case template](https://github.com/Islandora-CLAW/CLAW/wiki/Use-Case-template), prepending "Use Case:" to the title of the issue. +If you would like to submit a use case to the Islandora 8 project, please submit an issue [here](https://github.com/Islandora-CLAW/CLAW/issues/new) using the [Use Case template](https://github.com/Islandora-CLAW/CLAW/wiki/Use-Case-template), prepending "Use Case:" to the title of the issue. ### Documentation diff --git a/docs/islandora/drupal-bundle-configurations.md b/docs/islandora/drupal-bundle-configurations.md index a42d6189e..214c4aef4 100644 --- a/docs/islandora/drupal-bundle-configurations.md +++ b/docs/islandora/drupal-bundle-configurations.md @@ -1,8 +1,8 @@ ## Drupal Bundle Configurations -In Islandora CLAW, [content models](https://github.com/Islandora/islandora/wiki/Content-Models) are primarily created using content types (also known as node bundles) and media bundles. [Bundles](https://www.drupal.org/docs/8/api/entity-api/bundles) are defined by [YAML](http://befused.com/drupal/yaml) configuration files. [To create new content models](https://www.drupal.org/docs/8/api/entity-api/creating-a-custom-content-type-in-drupal-8), one would create the needed content types and media bundles via UI, then export the yml files related for those bundles using Configuration Synchronization (`http://localhost:8000/admin/config/development/configuration`) or [Features](https://www.drupal.org/project/features). An understanding about the structure of a bundle and various configuration files used to define it helps in creating and updating it. +In Islandora 8, [content models](https://github.com/Islandora/islandora/wiki/Content-Models) are primarily created using content types (also known as node bundles) and media bundles. [Bundles](https://www.drupal.org/docs/8/api/entity-api/bundles) are defined by [YAML](http://befused.com/drupal/yaml) configuration files. [To create new content models](https://www.drupal.org/docs/8/api/entity-api/creating-a-custom-content-type-in-drupal-8), one would create the needed content types and media bundles via UI, then export the yml files related for those bundles using Configuration Synchronization (`http://localhost:8000/admin/config/development/configuration`) or [Features](https://www.drupal.org/project/features). An understanding about the structure of a bundle and various configuration files used to define it helps in creating and updating it. -Content types and media bundles can be thought of as web [forms](https://www.drupal.org/docs/user_guide/en/structure-widgets.html) consisting of fields. Drupal provides [widgets](https://www.drupal.org/docs/8/creating-custom-modules/create-a-custom-field-widget) to define the behavior of a field and field storage to define how the data is stored in the database. Drupal provides various [display modes](https://www.drupal.org/docs/8/api/entity-api/display-modes-view-modes-and-form-modes) to show the forms to user when they are editing (Manage form display) or viewing (Manage display). +Content types and media bundles can be thought of as web [forms](https://www.drupal.org/docs/user_guide/en/structure-widgets.html) consisting of fields. Drupal provides [widgets](https://www.drupal.org/docs/8/creating-custom-modules/create-a-custom-field-widget) to define the behavior of a field and field storage to define how the data is stored in the database. Drupal provides various [display modes](https://www.drupal.org/docs/8/api/entity-api/display-modes-view-modes-and-form-modes) to show the forms to user when they are editing (Manage form display) or viewing (Manage display). A content model is packaged as a module for installation. All yml files are put in `config/install` folder of the module. Note that not all content models would contain media bundles. @@ -45,7 +45,7 @@ core.entity_view_display.node.your_content_type.default.yml core.entity_view_display.node.your_content_type.teaser.yml ``` -In addition, CLAW needs a RDF mapping to express the content in RDF and to sync to fedora. There will be one RDF mapping per bundle. +In addition, Islandora needs a RDF mapping to express the content in RDF and to sync to fedora. There will be one RDF mapping per bundle. ``` rdf.mapping.media.your_media_bundle.yml rdf.mapping.node.your_content_type.yml diff --git a/docs/islandora/rdf-mapping.md b/docs/islandora/rdf-mapping.md index 41ce56bc5..8756a3384 100644 --- a/docs/islandora/rdf-mapping.md +++ b/docs/islandora/rdf-mapping.md @@ -1,12 +1,12 @@ ## RDF Mapping -RDF mapping is aligning drupal fields to RDF ontology properties. For example the `title` field of a content model can be mapped to `dcterms:title` and/or `schema:title`. In Islandora CLAW, triples expressed by these mappings get synced to Fedora and indexed in the Blazegraph triplestore. +RDF mapping is aligning drupal fields to RDF ontology properties. For example the `title` field of a content model can be mapped to `dcterms:title` and/or `schema:title`. In Islandora 8, triples expressed by these mappings get synced to Fedora and indexed in the Blazegraph triplestore. Drupal provides default RDF mappings for its core entities. For instance, the article content type's RDF mapping is specified in the `rdf.mapping.node.page.yml` config. One can export this RDF mapping by going to Configuration Synchronization: `http://localhost:8000/admin/config/development/configuration/single/export`, selecting `RDF` for Configuration type and choosing `node.article`. -RDF mappings are defined/stored in Drupal as a YAML file. Currently, Drupal 8 does not have a UI to create/update RDF mappings to ontologies other than Schema.org. There is a project underway to develop a [UI](https://github.com/Islandora-CLAW/CLAW/issues/647) to support RDF mappings to any ontology. However, until then exporting/importing RDF yml files via Configuration Synchronization is the primary method to create/update RDF mappings. +RDF mappings are defined/stored in Drupal as a YAML file. Currently, Drupal 8 does not have a UI to create/update RDF mappings to ontologies other than Schema.org. There is a project underway to develop a [UI](https://github.com/Islandora-CLAW/CLAW/issues/647) to support RDF mappings to any ontology. However, until then exporting/importing RDF yml files via Configuration Synchronization is the primary method to create/update RDF mappings. ### Structure of RDF YAML file -Below is an example of RDF mapping. It is the current version of the RDF mapping of islandora collection content model (`rdf.mapping.node_type.collection.yml`). `types` specify the `rdf:type` of the resource or content model. `fieldMappings` specify all fields of that bundle and their RDF property mappings. One field can be mapped to more than one RDF property. It is a simple flat list. +Below is an example of RDF mapping. It is the current version of the RDF mapping of Islandora collection content model (`rdf.mapping.node_type.collection.yml`). `types` specify the `rdf:type` of the resource or content model. `fieldMappings` specify all fields of that bundle and their RDF property mappings. One field can be mapped to more than one RDF property. It is a simple flat list. types and fieldMappings ```yml @@ -21,7 +21,7 @@ dependencies: module: - islandora_collection id: node.islandora_collection -targetEntityType: node +targetEntityType: node bundle: islandora_collection types: - 'pcdm:Collection' @@ -54,11 +54,11 @@ fieldMappings: ``` ### Viewing RDF mapping of a resource -Please see the following tutorial to configure and view resources via REST request: +Please see the following tutorial to configure and view resources via REST request: [An Introduction to RESTful Web Services in Drupal 8](https://drupalize.me/blog/201401/introduction-restful-web-services-drupal-8). To get the JsonLD mapping, use jsonld format. Example request url: `http://localhost:8000/node/1?_format=jsonld` ### Altering an existing RDF mapping -Each Islandora CLAW content models come with a RDF mapping. It can be exported similar to above article's rdf mapping, modified and imported back by going to here: `http://localhost:8000/admin/config/development/configuration/single/import`. +Each Islandora content models come with a RDF mapping. It can be exported similar to above article's rdf mapping, modified and imported back by going to here: `http://localhost:8000/admin/config/development/configuration/single/import`. ### Defining a new RDF mapping A RDF mapping need to be created for a new or custom content model/type. The following steps describe the procedure: @@ -66,7 +66,5 @@ A RDF mapping need to be created for a new or custom content model/type. The fol * Export form display yml to get the list of the fields (ex `core.entity_form_display.node.your_content_type.default.yml`) * Remove any cache and uuid related elements * Add/modify the fields and ontology properties as needed, following the same syntax -* Name it following the convention (ex `rdf.mapping.node_type.your_content_type.yml`) +* Name it following the convention (ex `rdf.mapping.node_type.your_content_type.yml`) * Import it by going to `http://localhost:8000/admin/config/development/configuration/single/import` - - diff --git a/docs/mvp/mvp_doc.md b/docs/mvp/mvp_doc.md index 24f571962..db3592c6d 100644 --- a/docs/mvp/mvp_doc.md +++ b/docs/mvp/mvp_doc.md @@ -1,14 +1,14 @@ -# Islandora CLAW MVP +# Islandora 8 MVP ## Motivation -The Islandora CLAW project is currently transitioning from a prototype into a competitive product, and has had a requirements change from integration with Drupal 7 to Drupal 8. In order to aid in that transition, we are defining the minimum viable product. This will defend against scope creep, give clearly defined goals for community members to work towards, and present the point at which the CLAW team feels the software is ready to be tested out in small installations. +The Islandora 8 project is currently transitioning from a prototype into a competitive product, and has had a requirements change from integration with Drupal 7 to Drupal 8. In order to aid in that transition, we are defining the minimum viable product. This will defend against scope creep, give clearly defined goals for community members to work towards, and present the point at which the development team feels the software is ready to be tested out in small installations. Needless to say, since this is a minimum product, a lot of parts of the previous prototype are either going to get replaced by an existing project to ease the maintenance load, or be removed altogether until time and resources allow other development. ## High Level Features -These are what are considered the minimum requirements for a functional Islandora CLAW that is worthy of a 1.0.0 release. +These are what are considered the minimum requirements for a functional Islandora 8 that is worthy of a 1.0.0 release. * Content modeled in Drupal as Entities using [PCDM](https://github.com/duraspace/pcdm/wiki) 1.0 @@ -30,7 +30,7 @@ These are what are considered the minimum requirements for a functional Islandor ### Overview Islandora is composed of four broad categories of technologies. On one end, there is the administrative interface, which users and other clients will interact with. On the other is a repository, which will hold binary data and RDF triples. In between the two are connectors, which are small pieces of software that react to events from either administrative interface or the repository. These connectors will utilize microservices -- small utilities exposed as web services either internally or out on the internet at large. -![High Level Diagram of Islandora CLAW](https://raw.githubusercontent.com/Islandora-CLAW/CLAW/masterhttps://raw.githubusercontent.com/Islandora-CLAW/CLAW/master/docs/assets/image11.png) +![High Level Diagram of Islandora 8](https://raw.githubusercontent.com/Islandora-CLAW/CLAW/masterhttps://raw.githubusercontent.com/Islandora-CLAW/CLAW/master/docs/assets/image11.png) ### Administrative Interface diff --git a/docs/technical-documentation/drupal-project.md b/docs/technical-documentation/drupal-project.md index 25c8a6833..a96ea995b 100644 --- a/docs/technical-documentation/drupal-project.md +++ b/docs/technical-documentation/drupal-project.md @@ -1,6 +1,6 @@ # Introduction -Islandora CLAW makes use of [drupal-project](https://github.com/drupal-composer/drupal-project), a composer template for Drupal projects. We augment it with Islandora CLAW specific changes, and need to occasionally pull in upstream changes. The process below outlines how we will do it in a consistent manner. +Islandora 8 makes use of [drupal-project](https://github.com/drupal-composer/drupal-project), a composer template for Drupal projects. We augment it with Islandora specific changes, and need to occasionally pull in upstream changes. The process below outlines how we will do it in a consistent manner. # Pull in upstream changes @@ -10,7 +10,7 @@ Islandora CLAW makes use of [drupal-project](https://github.com/drupal-composer/
`git remote add upstream https://github.com/drupal-composer/drupal-project.git` 3. Fetch everything:
`git fetch --all` -4. Create a branch to pull in changes that is based off the Islandora-CLAW 8.x-1.x branch: +4. Create a branch to pull in changes that is based off the Islandora 8.x-1.x branch:
`git checkout -b sync-upstream` 5. Rebase upstream changes:
`git rebase upstream/8.x` (fix any merge conflicts, and then `git rebase --continue`) diff --git a/docs/technical-documentation/versioning.md b/docs/technical-documentation/versioning.md index 28a7a8f96..90b774150 100644 --- a/docs/technical-documentation/versioning.md +++ b/docs/technical-documentation/versioning.md @@ -1,6 +1,6 @@ # Versioning Policy -Islandora CLAW uses [semantic versioning](http://semver.org/), except for Drupal modules. +Islandora 8 uses [semantic versioning](http://semver.org/), except for Drupal modules. ## Components diff --git a/docs/user-documentation/CLAWfor1x.md b/docs/user-documentation/CLAWfor1x.md deleted file mode 100644 index 0bd268d0d..000000000 --- a/docs/user-documentation/CLAWfor1x.md +++ /dev/null @@ -1,44 +0,0 @@ -# What's Different Between Islandora 1.x and Islandora CLAW - -In the most basic terms, Islandora CLAW is the version of Islandora that works with [Fedora 4](https://wiki.duraspace.org/display/FEDORA4x/Fedora+4.x+Documentation). Because Fedora 4 is a vastly different platform than Fedora 3, so too is Islandora CLAW a major departure from what came before. Switching to CLAW represents not just a typical upgrade with improvements, features, and bug fixes, but rather a major shift in how objects are stored and managed. - -Moving from Islandora 7.x-1.x to CLAW requires a migration of objects, which you can learn about [here](../migration/migration.md). It also requires some adjustments in how you think about your objects and their relationships, and how to manage them in Islandora, which we will cover below. - -You can also check out some of the documentation provided by the Fedora project: -* [Concept Mapping - Fedora 3 to 4](https://wiki.duraspace.org/display/FEDORA4x/Concept+Mapping+-+Fedora+3+to+4) -* [The Fedora 4 object model](https://wiki.duraspace.org/display/FEDORA4x/The+Fedora+4+object+model) -* [Fedora 3 to 4 Upgration](https://wiki.duraspace.org/display/FF/Fedora+3+to+4+Upgration) -* [LDP-PCDM-F4 In Action](https://wiki.duraspace.org/display/FEDORA4x/LDP-PCDM-F4+In+Action) - -## Fedora - -### Repository Structure - -Fedora 3 stored all objects at the top level of the repository, although presentation of the objects could mimic a directory structure by having objects 'in' collections and collections 'in' other collections. This image is a helpful oversimplification: - -![image](https://cloud.githubusercontent.com/assets/2371345/10912108/525c2a0e-821e-11e5-9c5b-d853b62f1e5a.png) - -Fedora 4 differs considerably in that there is an innate tree hierarchy to the repository rather than a flat structure. Put less simply, "[a Fedora 4 repository consists of a directed acyclic graph of resources where edges represent a parent-child relation](https://wiki.duraspace.org/display/FEDORA4x/The+Fedora+4+object+model)". - -### Object Structure -Fedora 3 objects are FOXML (Fedora Object eXtensible Markup Language) documents, with three elements: - -* `Digital Object Identifier`: A unique, persistent identifier for the digital object. Also known as the PID. -* `System Properties`: A set of system-defined descriptive properties that is necessary to manage and track the object in the repository. -* `Datastream(s)`: The element in a Fedora digital object that represents a content item. - -In Fedora 4 , what we would have called `objects` are now referred to as [`Resources`](https://www.w3.org/TR/ld-glossary/#resource) (and *everything* in Fedora 4 is a `Resource`). Instead of being composed of XML as they were in Fedora 3, they are stored in [ModeShape](http://modeshape.jboss.org/) as nodes with RDF properties. `Resources` come in two flavors: [`RDF Sources`](https://www.w3.org/TR/ldp/#ldpr-resource), which are `Resources` having only RDF data, and [`Non-RDF Sources`](https://www.w3.org/TR/ldp/#dfn-linked-data-platform-non-rdf-source), which are `Resources` that are binary files (HTML, PDFs, images, audio, video, etc). The terms [`RDF Source`] and [`Non-RDF Source`] both come from the [W3C's](https://www.w3.org/) [Linked Data Platform](https://www.w3.org/TR/ldp/) specification, which also defines the idea of [Linked Data Platform Containers](https://www.w3.org/TR/ldp/#dfn-linked-data-platform-container), or `LDPCs`. An `LDPC` is an `RDF Source` that functions as a collection of `Resources`, similar to the way Islandora 7.x-1.x compound objects exist only as a way to tie together its children. An `LDPC` may contain `Non-RDF Sources`, as well as other `RDF Sources` acting as `LDPCs`; you can have a container of containers just like how Islandora 7.x-1.x can have a collection of collections. - -CLAW makes use of the [Portland Common Data Model (PCDM)](https://github.com/duraspace/pcdm/wiki) as a layer of abstraction over `LDPCs` to make containment simpler to understand for users; a `pcdm:Collection` may contain other `pcdm:Collections` or `pcdm:Objects` (similar to an Islandora 7.x-1.x collection content model), and a `pcdm:Object` may contain other `pcdm:Objects` (similar to the way an Islandora 7.x-1.x compound object has child objects) or `pcdm:Files` (similar to the way Islandora 7.x-1.x objects have datastreams). - -### Datastreams -In Islandora 7.x-1.x, every object has a specific content model which defined what datastreams it could have and which were absolutely required. Some of these Islandora 7.x-1.x datastreams contained metadata about the object while others contained binary files (JPG, PDF, MP3, PNG, TIFF, etc). In Islandora CLAW, all metadata about a resource is stored as RDF attributes directly on the resource itself, whether that resource is a `pcdm:Collection`, `pcdm:Object` or a `pcdm:File`, so we no longer need to separate metadata by type (RELS-EXT, RELS-INT, MODS, DC, PREMIS, etc) and store it in binary files as we did in Islandora 7.x-1.x. - -Binary files, such as JPGs, PNGs, MP3s, and PDFs, are handled via `pcdm:Files` which are contained by a parent `pcdm:Object`, similar to how an Islandora 7.x-1.x cmodel may hold a PDF or JPG as a datastream. Unlike Islandora 7.x-1.x, these binary files can actually have their own technical metadata attached them. This is because `pcdm:Collections`, `pcdm:Objects` and even `pcdm:Files` are all `RDF Sources` containing only RDF data, with `pcdm:Files` having links to the URL of the `Non-RDF Source` (binary file) they represent as part of their RDF data in addition to whatever other metadata you may want about the file. Using this system, a `pcdm:Object` can contain as many `pcdm:Files` as necessary, and each `pcdm:File` can have separate metadata about itself and its relationship to other `pcdm:Files` attached to the parent `pcdm:Object`, serving the same purpose RELS-INT datastreams served in Islandora 7.x-1.x. - -Note that you *can* use a `pcdm:File` to represent a file of metadata, such as MODS, DC, or PBCore, in case you would like to preserve a copy of an object's legacy metadata when migrating into Fedora 4. These metadata files will be treated like any other binary file in Islandora CLAW, and will not be indexed or editable through the GUI. - -#### PIDs -Every object in a Fedora 3 repository had a Persistent Identifier following the pattern `namespace:pid`. Fedora 4 resources do not have PIDs. Instead, since Fedora 4 is an [LDP server](https://www.w3.org/ns/ldp), their identifiers are fundamentally their URIs. The PIDs of objects migrated from a Fedora 3 repository can still be stored in Fedora 4, as additional properties on the new Fedora 4 resource. - -Since resources are stored as `nodes` on the Drupal side of Islandora CLAW, they also have Drupal UUIDs. diff --git a/docs/user-documentation/content_types.md b/docs/user-documentation/content_types.md index 7b78ad6a8..dec0eb336 100644 --- a/docs/user-documentation/content_types.md +++ b/docs/user-documentation/content_types.md @@ -1,7 +1,7 @@ # Create / Update a Content Type !!! note "Islandora Demo" - The screenshots and pre-existing data in this documentation assume that you are using the [Islandora Demo](https://github.com/Islandora-CLAW/islandora_demo) configuration. + The screenshots and pre-existing data in this documentation assume that you are using the [Islandora Defaults](https://github.com/Islandora-CLAW/islandora_demo) configuration. !!! note "Graphical User Interface" This page will address how to create and modify ingest forms (or rather, content types) via the GUI. For help working with forms via the API, please check out the [Further Reading](#further-reading) section for links to more advanced Drupal documentation. diff --git a/docs/user-documentation/different_from_7x.md b/docs/user-documentation/different_from_7x.md new file mode 100644 index 000000000..e55f05dd8 --- /dev/null +++ b/docs/user-documentation/different_from_7x.md @@ -0,0 +1,44 @@ +# What's Different Between Islandora 1.x and Islandora 8.x + +In the most basic terms, Islandora 8 is the version of Islandora that works with [Fedora 5](https://wiki.duraspace.org/display/FF/Fedora+Repository+Home). Because Fedora 4 and 5 are vastly different than Fedora 3, so too is Islandora 8 a major departure from what came before. Switching to Islandora 8 represents not just a typical upgrade with improvements, features, and bug fixes, but rather a major shift in how objects are stored and managed. + +Moving from Islandora 7.x-1.x to 8.x-1.x requires a migration of objects, which you can learn about [here](../migration/migration.md). It also requires some adjustments in how you think about your objects and their relationships, and how to manage them in Islandora, which we will cover below. + +You can also check out some of the documentation provided by the Fedora project: +* [Concept Mapping - Fedora 3 to 4](https://wiki.duraspace.org/display/FEDORA4x/Concept+Mapping+-+Fedora+3+to+4) +* [The Fedora 5 object model](https://wiki.duraspace.org/display/FEDORA5x/The+Fedora+object+model) +* [Fedora 3 to 4 Upgration](https://wiki.duraspace.org/display/FF/Fedora+3+to+4+Upgration) +* [LDP-PCDM-F4 In Action](https://wiki.duraspace.org/display/FEDORA4x/LDP-PCDM-F4+In+Action) + +## Fedora + +### Repository Structure + +Fedora 3 stored all objects at the top level of the repository, although presentation of the objects could mimic a directory structure by having objects 'in' collections and collections 'in' other collections. This image is a helpful oversimplification: + +![image](https://cloud.githubusercontent.com/assets/2371345/10912108/525c2a0e-821e-11e5-9c5b-d853b62f1e5a.png) + +Fedora 4/5 differs considerably in that there is an innate tree hierarchy to the repository rather than a flat structure. Put less simply, "[a Fedora repository consists of a directed acyclic graph of resources where edges represent a parent-child relation](https://wiki.duraspace.org/display/FEDORA5x/The+Fedora+object+model)". + +### Object Structure +Fedora 3 objects are FOXML (Fedora Object eXtensible Markup Language) documents, with three elements: + +* `Digital Object Identifier`: A unique, persistent identifier for the digital object. Also known as the PID. +* `System Properties`: A set of system-defined descriptive properties that is necessary to manage and track the object in the repository. +* `Datastream(s)`: The element in a Fedora digital object that represents a content item. + +In Fedora 4/5 , what we would have called `objects` are now referred to as [`Resources`](https://www.w3.org/TR/ld-glossary/#resource) (and *everything* in Fedora 4/5 is a `Resource`). Instead of being composed of XML as they were in Fedora 3, they are stored in [ModeShape](http://modeshape.jboss.org/) as nodes with RDF properties. `Resources` come in two flavors: [`RDF Sources`](https://www.w3.org/TR/ldp/#ldpr-resource), which are `Resources` having only RDF data, and [`Non-RDF Sources`](https://www.w3.org/TR/ldp/#dfn-linked-data-platform-non-rdf-source), which are `Resources` that are binary files (HTML, PDFs, images, audio, video, etc). The terms [`RDF Source`] and [`Non-RDF Source`] both come from the [W3C's](https://www.w3.org/) [Linked Data Platform](https://www.w3.org/TR/ldp/) specification, which also defines the idea of [Linked Data Platform Containers](https://www.w3.org/TR/ldp/#dfn-linked-data-platform-container), or `LDPCs`. An `LDPC` is an `RDF Source` that functions as a collection of `Resources`, similar to the way Islandora 7.x-1.x compound objects exist only as a way to tie together its children. An `LDPC` may contain `Non-RDF Sources`, as well as other `RDF Sources` acting as `LDPCs`; you can have a container of containers just like how Islandora 7.x-1.x can have a collection of collections. + +Islandora 8.x-1.x makes use of the [Portland Common Data Model (PCDM)](https://github.com/duraspace/pcdm/wiki) as a layer of abstraction over `LDPCs` to make containment simpler to understand for users; a `pcdm:Collection` may contain other `pcdm:Collections` or `pcdm:Objects` (similar to an Islandora 7.x-1.x collection content model), and a `pcdm:Object` may contain other `pcdm:Objects` (similar to the way an Islandora 7.x-1.x compound object has child objects) or `pcdm:Files` (similar to the way Islandora 7.x-1.x objects have datastreams). + +### Datastreams +In Islandora 7.x-1.x, every object has a specific content model which defined what datastreams it could have and which were absolutely required. Some of these Islandora 7.x-1.x datastreams contained metadata about the object while others contained binary files (JPG, PDF, MP3, PNG, TIFF, etc). In Islandora 8.x-1.x, all metadata about a resource is stored as RDF attributes directly on the resource itself, whether that resource is a `pcdm:Collection`, `pcdm:Object` or a `pcdm:File`, so we no longer need to separate metadata by type (RELS-EXT, RELS-INT, MODS, DC, PREMIS, etc) and store it in binary files as we did in Islandora 7.x-1.x. + +Binary files, such as JPGs, PNGs, MP3s, and PDFs, are handled via `pcdm:Files` which are contained by a parent `pcdm:Object`, similar to how an Islandora 7.x-1.x cmodel may hold a PDF or JPG as a datastream. Unlike Islandora 7.x-1.x, these binary files can actually have their own technical metadata attached them. This is because `pcdm:Collections`, `pcdm:Objects` and even `pcdm:Files` are all `RDF Sources` containing only RDF data, with `pcdm:Files` having links to the URL of the `Non-RDF Source` (binary file) they represent as part of their RDF data in addition to whatever other metadata you may want about the file. Using this system, a `pcdm:Object` can contain as many `pcdm:Files` as necessary, and each `pcdm:File` can have separate metadata about itself and its relationship to other `pcdm:Files` attached to the parent `pcdm:Object`, serving the same purpose RELS-INT datastreams served in Islandora 7.x-1.x. + +Note that you *can* use a `pcdm:File` to represent a file of metadata, such as MODS, DC, or PBCore, in case you would like to preserve a copy of an object's legacy metadata when migrating into Fedora 4. These metadata files will be treated like any other binary file in Islandora 8.x-1.x, and will not be indexed or editable through the GUI. + +#### PIDs +Every object in a Fedora 3 repository had a Persistent Identifier following the pattern `namespace:pid`. Fedora 4/5 resources do not have PIDs. Instead, since Fedora 4 is an [LDP server](https://www.w3.org/ns/ldp), their identifiers are fundamentally their URIs. The PIDs of objects migrated from a Fedora 3 repository can still be stored in Fedora 4/5, as additional properties on the new Fedora 4 resource. + +Since resources are stored as `nodes` on the Drupal side of Islandora 8.x-1.x, they also have Drupal UUIDs. diff --git a/docs/user-documentation/intro-to-ld-for-claw.md b/docs/user-documentation/intro-to-ld-for-islandora-8.md similarity index 89% rename from docs/user-documentation/intro-to-ld-for-claw.md rename to docs/user-documentation/intro-to-ld-for-islandora-8.md index aaaa29245..259164920 100644 --- a/docs/user-documentation/intro-to-ld-for-claw.md +++ b/docs/user-documentation/intro-to-ld-for-islandora-8.md @@ -1,5 +1,5 @@ -# Introduction to Linked Data for CLAW -The purpose of this page is to provide a guided reading list to anyone who wants to get up to speed on the basics of linked data within the Islandora community. Those who make their way through the readings will be able to talk competently about linked data and better understand the design decisions made in Islandora CLAW. The list starts with the fundamentals of linked data (RDF, SPARQL, serializations and ontologies) and moves toward more advanced topics specific to the use cases of a Fedora 4 based digital repository system. +# Introduction to Linked Data for Islandora 8 +The purpose of this page is to provide a guided reading list to anyone who wants to get up to speed on the basics of linked data within the Islandora community. Those who make their way through the readings will be able to talk competently about linked data and better understand the design decisions made in Islandora 8. The list starts with the fundamentals of linked data (RDF, SPARQL, serializations and ontologies) and moves toward more advanced topics specific to the use cases of a Fedora 4 based digital repository system. # Basics of Linked Data This section seeks to give the reader a foundational understanding of what linked data is, why it is useful, and a very superficial understanding of how it works. @@ -31,7 +31,7 @@ This section takes a look at SPARQL, the query language that allows you to ask l - [DBpedia's SPARQL Endpoint](https://dbpedia.org/sparql) # RDF Serialization Formats -RDF data can be translated into many different formats. RDF/XML is the original way that RDF data was shared, but there are much more human-friendly serialization formats like Turtle which is great for beginners. JSON-LD is the easiest format for applications to use, and is the serialization format that CLAW uses internally. Make sure to check out the [JSON-LD Playground](http://json-ld.org/playground/) for an interactive learning experience. +RDF data can be translated into many different formats. RDF/XML is the original way that RDF data was shared, but there are much more human-friendly serialization formats like Turtle which is great for beginners. JSON-LD is the easiest format for applications to use, and is the serialization format that Islandora 8 uses internally. Make sure to check out the [JSON-LD Playground](http://json-ld.org/playground/) for an interactive learning experience. - [Wikipedia article on Serialization](https://en.wikipedia.org/wiki/Serialization) - [W3C’s RDF/XML Syntax Specification](https://www.w3.org/TR/REC-rdf-syntax/) @@ -62,7 +62,7 @@ One isn't limited to the ontologies & vocabularies that already exist in the wor - [W3C’s OWL 2 Quick Reference](https://www.w3.org/TR/owl2-quick-reference/) # Repository-Specific Ontologies -Most ontologies are very specific to certain use cases, and digital repository systems are no different. This section covers ontologies that are of specific interest to users of CLAW, or any Fedora 4 based digital repository system. +Most ontologies are very specific to certain use cases, and digital repository systems are no different. This section covers ontologies that are of specific interest to users of Islandora 8, or any Fedora 4 based digital repository system. - [MODS RDF Namespace Document](http://www.loc.gov/standards/mods/modsrdf/v1/) - [MODS RDF Ontology Primer](https://www.loc.gov/standards/mods/modsrdf/primer.html) @@ -72,6 +72,6 @@ Most ontologies are very specific to certain use cases, and digital repository s - [LDP 1.0 Specification](https://www.w3.org/TR/ldp/) - [Portland Common Data Model (PCDM) wiki)](https://github.com/duraspace/pcdm/wiki) - [PCDM ontologies list](http://pcdm.org/) -- [PCDM Models ontology (defines Collections, Objects & Files)](http://pcdm.org/2016/04/18/models) +- [PCDM Models ontology (defines Collections, Objects & Files)](http://pcdm.org/2016/04/18/models) - [Fedora ontologies](http://fedora.info/) - [CLAWntology](https://github.com/Islandora-CLAW/CLAWntology) From e8acbf22168d191a3b7c600f8175fd549cb9c5e0 Mon Sep 17 00:00:00 2001 From: Seth Shaw Date: Thu, 27 Jun 2019 07:42:36 -0700 Subject: [PATCH 2/2] Update CONTRIBUTING.md --- CONTRIBUTING.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26060539d..916d6794e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,10 @@ If you are reading this document then you are interested in contributing to Islandora 8. All contributions are welcome: use-cases, documentation, code, patches, bug reports, feature requests, etc. You do not need to be a programmer to speak up! +We also have an irc channel -- #islandora -- on freenode.net. Feel free to hang out there, ask questions, and help others out if you can. + +Please note that this project operates under the [Islandora Community Code of Conduct](http://islandora.ca/codeofconduct). By participating in this project you agree to abide by its terms. + ## Workflows The group meets each Wednesday at 1:00 PM Eastern. Meeting notes and announcements are posted to the [Islandora community list](https://groups.google.com/forum/#!forum/islandora) and the [Islandora developers list](https://groups.google.com/forum/#!forum/islandora-dev). You can view meeting agendas, notes, and call-in information [here](https://github.com/Islandora-CLAW/CLAW/wiki#islandora-claw-tech-calls). Anybody is welcome to join the calls, and add items to the agenda. @@ -16,11 +20,11 @@ You can contribute documentation in two different ways. One way is to create an ### Request a new feature -To request a new feature you should [open an issue in the CLAW repository](https://github.com/Islandora-CLAW/CLAW/issues/new) or create a use case (see the _Use cases_ section above), and summarize the desired functionality. Prepend "Enhancement:" if creating an issue on the project repo, and "Use Case:" if creating a use case. +To request a new feature you should [open an issue in the Islandora 8 repository](https://github.com/Islandora-CLAW/CLAW/issues/new) or create a use case (see the _Use cases_ section above), and summarize the desired functionality. Prepend "Enhancement:" if creating an issue on the project repo, and "Use Case:" if creating a use case. ### Report a bug -To report a bug you should [open an issue in the CLAW repository](https://github.com/Islandora-CLAW/CLAW/issues/new) that summarizes the bug. Prepend the label "Bug:" to the title of the issue. +To report a bug you should [open an issue in the Islandora 8 repository](https://github.com/Islandora-CLAW/CLAW/issues/new) that summarizes the bug. Prepend the label "Bug:" to the title of the issue. In order to help us understand and fix the bug it would be great if you could provide us with: @@ -66,4 +70,4 @@ You may want to read [Syncing a fork](https://help.github.com/articles/syncing-a ## License Agreements -The Islandora Foundation requires that contributors complete a [Contributor License Agreement](http://islandora.ca/sites/default/files/islandora_cla.pdf) or be covered by a [Corporate Contributor License Agreement](http://islandora.ca/sites/default/files/islandora_ccla.pdf). The signed copy of the license agreement should be sent to community@islandora.ca. This license is for your protection as a contributor as well as the protection of the Foundation and its users; it does not change your rights to use your own contributions for any other purpose. +The Islandora Foundation requires that contributors complete a [Contributor License Agreement](http://islandora.ca/sites/default/files/islandora_cla.pdf) or be covered by a [Corporate Contributor License Agreement](http://islandora.ca/sites/default/files/islandora_ccla.pdf). The signed copy of the license agreement should be sent to community@islandora.ca. This license is for your protection as a contributor as well as the protection of the Foundation and its users; it does not change your rights to use your own contributions for any other purpose. A list of current CLAs is kept [here](https://github.com/Islandora/islandora/wiki/Contributor-License-Agreements).