Added funding as reverse of fundedItem

[stain]

See #383 discussion #383 (comment)

To avoid adding to Thing I made the domainIncludes more specific to
CreativeWork, Organization or Person.

Perhaps rangeIncludes in fundedItems should be updated accordingly.

[stain]

[RichardWallis]

@stain this PR is failing integration tests.

In your development environment does the scripts/run_tests.py script run successfully?

[stain]

Thanks @RichardWallis, I was puzzled by the null output from Travis.

Admittedly it is quite hard to get the gcloud development environment to work in the first place..even when using the https://hub.docker.com/r/google/cloud-sdk/ docker image:

======================================================================
FAIL: test_even_number_inverseOf (test_graphs.SDOGraphSetupTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/schemaorg/tests/test_graphs.py", line 89, in test_even_number_inverseOf
    "Even number of inverseOf triples expected. Found: %s " % len(inverseOf_results ) )
AssertionError: Even number of inverseOf triples expected. Found: 45 

I had forgot to do inverse both direction - see ff0819d (still a question for #383 folks if the domainIncludes of funding should exactly match the rangeIncludes of fundedItem - we may not want funding to appear on the property listing of every Thing?

[smrgeoinfo]

re the inverse question, I'd argue that if any Thing can be a fundedItem, for logical consistency, any Thing might have funding.

[RichardWallis]

I'd argue that if any Thing can be a fundedItem, for logical consistency, any Thing might have funding.

In principle, I would agree with you.

In practice, however, such a move would have significant impacts that should be seriously considered before proceeding. Adding Thing to the domainIncludes of a property will effectively add that property to 829 Types. For a large proportion of these types (Volcano, Review, Invoice, etc.) a funding property would make little sense and potentially cause confusion.

There needs to be a really strong use case, and examples of who would consume such data, to add properties to the Thing type.

[smrgeoinfo]

I see what you're saying, makes good practical sense. Logically the problem is in the definition of fundedItem. As you point out since the range of funded item is Thing, a grant can fund a Landform, Invoice etc. If the domain of funding is not the range of fundedItem then they shouldn't be defined as inverse properties. Options: 1. change the range of fundedItem, or 2. don't define funding and fundedItem as inverse properties.

What kinds of Thing can have funding...
Action -- probably some kinds of actions
CreativeWork -- yes
Event -- yes
Intangible --- probably not
MedicalEntity -- some subclasses?
Organization -- yes
Person -- yes
Place -- some sub classes?
Product -- some sub classes?

[stain]

@smrgeoinfo in an OWL world we would make fundedCreativeWork etc subproperties of fundedItem, and then we could inverse those. That is because in OWL the inverse properties will get all the inversed domain/ranges implied.

Alternatively make FundedCreativeWork etc. subclass that is equivalent to type=CreativeWork and funded ANY- but again very OWLy.

However in schema.org we are softer - e.g. even https://schema.org/domainIncludes itself is not exclusive - it just lists some of the classes that are valid domains (and hence later additions is not a problem). I can use a schema.org property like http://schema.org/creator on my own custom type http://example.com/Universe that does not fit into the schema.org hierarchy, and nothing weird is inferred or broken.

I don't know if the schema.org is consistent in opposite domain/range across the existing inverses.

Thus my reasoning, that even if any Thing is permitted in range of fundedItem (after all the grant could fund a https://schema.org/ExhibitionEvent or a https://schema.org/LocalBusiness); we don't need to inject funding into every type, but mainly from my point of view CreativeWork, Person and Organization.

I would not object to funding going into Event either, where it would go alongside the direct funder link.

If anything we can tighten a bit fundedItem to match, but describe on its page that it could also be used on other things. I don't think we need to add a catch-all subclass FundedItem although that would be another way out.

[stain]

@smrgeoinfo would it make sense that funding just gets matching domain as https://schema.org/funder ?

• CreativeWork
• Event
• MonetaryGrant
• Organization
• Person

Can add something like this to funder:

To further describe the monetary grant from the funder or sponsor, use funding

(Not sure about the recursion to MonetaryGrant - can a grant have its own funding grant? To be fair we've done that, e.g. student conference attendees got travel grants, which was funded by our own H2020 project funding, which again is funded by a large EU programme grant - but this might be mixing up with Project and FundingScheme.)

[smrgeoinfo]

I suppose a grant can be funded by multiple other grants. if its 1:1 that would be odd. On that basis, I think suggesting domain of funding to be {CreativeWork, Event, MonetaryGrant, Organization, Person} would be a reasonable solution.

[dr-shorthair]

AFAICT funding always relates to an activity.
Creative works are the outputs of activities - it is not the creative work that was funded, but the production of the creative work.

[stain]

Yes, @dr-shorthair there is an activity behind creating anything. The actual provenance then would detail how different work and people contributed to what aspects. We explore some of that in https://researchobject.github.io/ro-crate/1.0/#provenance-equipment-used-to-create-files - even there you will find use for a funding property because some equipment might have been sponsored by a grant.

Many funders require/encourage you to attribute their funding codes etc in their "research outputs" - and so this is basically this direct property, without having to expand on a detailed provenance chain. It is also filling the missing hole as the existing Grant example already use the funding property but it was somehow never added (probably because of the domain).

I'll modify this PR to reflect the types agreed with @smrgeoinfo - if you agree we can also change the range of fundedItems to be the same list.

[stain]

@RichardWallis how should I suggest an addition to the funder rdfs:comment text to add a line to relate it to funding property?

[RichardWallis]

See also discussion in issue #2258

[stain]

OK, I added further crosslink between funding and funder, just adding another rdfs:comment worked well.

As you see I also added links to the specific types FundingScheme and FundingAgency as at the moment they are hidden deep below Organization and Project. These are not always the right one (e.g. the funder might just be a person), but should be good to have deep-links so they can be used where appropriate.

[stain]

Sorry @RichardWallis although extending the rdfs:comment on funding worked for the site, it is not permitted by the test:

======================================================================
FAIL: test_propCommentCount (test_basics.SimpleSchemaIntegrityTests)

----------------------------------------------------------------------

Traceback (most recent call last):

  File "/home/travis/build/schemaorg/schemaorg/tests/test_basics.py", line 488, in test_propCommentCount

    self.assertEqual(len(prop_comment_errors), 0, "Comment count property errors. Aggregated: \n\n" + " \n\n".join(prop_comment_errors))

AssertionError: Comment count property errors. Aggregated: 

property 'funder': Expected 1 rdfs:comment, found: 2.

 A person or organization that supports (sponsors) something through some kind of financial contribution.

 AND

  This property can also be used to indicate funding from a particular [[FundingScheme]] or [[FundingAgency]].

To indicate a particular [[MonetaryGrant]] which supported the underlying work, combine with property [[funding]]. 

So I don't know how to do this cross-link, as the funding is in the pending extension but funder is already in core. Is there a secondary property I can use to augment existing funder with links to proposed funding?

[stain]

In 4ba1d8d to avoid that rdfs:comment clash I moved the crosslink from funder to schema.ttl but put guards on the referenced types being in pending section - as this would appear also in the "core"

[stain]

I rebased with master so the tests would pass (needing #2637)

It seems agreement has been reached, any chance of merging..?

[stain]

Ping to check what else is needed for this PR?

[ashepherd]

@RichardWallis @danbri

Would this benefit from a couple of examples?

Hi Richard, happy to contribute some examples from the sciences. If this is useful, I can help put together a pull request. Below you'll find 3 examples:

1. Dataset to Grant,
2. ResearchProject to Grant
3. Organization to Grant

each with links to web pages from our data repository.

Goal

In full appreciation of the complexity of this issue, maybe a simple, small change could help us move forward with a new property to say that some Thing was funded by some Grant. (the inverse of https://schema.org/fundedItem - see #2258)

Main reason for this property is to let repositories of Things point to the Grant that funded it.

Example screenshot from Zenodo

1. Zenodo lets you publish some Thing

2. You can specify what funding for that Thing

Understanding that in JSON-LD schema.org publishers can define a @graph on a page for some Thing and include 2 resources in the graph - the Thing and the Grant. Then use https://schema.org/fundedItem from the Grant to point to the Thing. However, in trying to keep things easy for schema.org publishers seems good to have a property to go from the Thing to the Grant.

Context

• Issue Request for inverse property of 'fundedItem' #2258

Proposed Change to schema.org

with an inverse property to the existing https://schema.org/fundedItem called funding (or something better):

  "@context": {
    "@vocab": "http://schema.org/",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "schema": "http://schema.org/"
  },
  "@id": "funding",
  "@type": "rdf:Property",
  "rdfs:comment": "Indicates a <a class=\"localLink\" href=\"http://schema.org/Grant\">Grant</a> that funded some Thing.",
  "rdfs:label": "fundedBy",
  "schema:domainIncludes": {
    "@id": "Thing"
  },
  "schema:inverseOf": {
    "@id": "fundedItem"
  },
  "schema:rangeIncludes": {
    "@id": "Grant"
  }
}

EXAMPLES

Example 1: Dataset -> Grant

URL: https://www.bco-dmo.org/dataset/3300

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  "name": "larval krill pigments",
  "url": "https://www.bco-dmo.org/dataset/3300",
  "publisher": { "@id": "https://www.bco-dmo.org" },
  "funding": {
    "@type": "Grant",
    "name": "GLOBEC: Winter Ecology of Larval Krill: Quantifying their Interaction with the Pack Ice Habitat",
    "alternateName": "ANT-9909933",
    "url": "https://www.nsf.gov/awardsearch/showAward?AWD_ID=9909933",
    "funder": {
      "@type": "FundingAgency",
      "name": "National Science Foundation",
      "alternateName":  "NSF",
      "sameAs": "https://doi.org/10.13039/100000001"
    }
  }
}

Example 2: ResearchProject -> Grant

URL: https://www.bco-dmo.org/project/2039
Context: the Dataset from Example 1 was created out of a larger research project that was funded by 3 grants.

{
  "@context": "http://schema.org/",
  "@type": "ResearchProject",
  "name": "U.S. GLOBEC Southern Ocean",
  "url": "https://www.bco-dmo.org/project/2039",
  "funding": [
    {
      "@type": "MonetaryGrant",
      "name": "Foraging Ecology of Crabeater Seals (Lobodon Carcinophagus)",
      "alternateName": "ANT-9909933",
      "url": "https://www.bco-dmo.org/award/54719",
      "sameAs": "https://www.nsf.gov/awardsearch/showAward?AWD_ID=9909933",
      "funder": {
        "@id": "https://doi.org/10.13039/100000162",
        "@type": "FundingAgency",
        "name": "NSF Antarctic Sciences",
        "alternateName": "NSF ANT",
        "url": "https://www.bco-dmo.org/funding-source/369",
        "sameAs": "https://doi.org/10.13039/100000162",
        "parentOrganization": {
          "@type": "FundingAgency",
          "name": "National Science Foundation",
          "alternateName":  "NSF",
          "sameAs": "https://doi.org/10.13039/100000001"
        }
      }
    },
    {
      "@type": "MonetaryGrant",
      "name": "GLOBEC: Sea Ice Microbial Communities",
      "alternateName": "ANT-9910098",
      "url": "https://www.bco-dmo.org/award/54688",
      "sameAs": "https://www.nsf.gov/awardsearch/showAward?AWD_ID=9910098",
      "funder": {"@id": "https://doi.org/10.13039/100000162"}
    },
    {
      "@type": "MonetaryGrant",
      "name": "unknown SOGLOBEC NSF ANT",
      "url": "https://www.bco-dmo.org/award/54617",
      "funder": {"@id": "https://doi.org/10.13039/100000162"}
    }
  ]
}

Example 3: Organization -> Grant

URL: https://www.bco-dmo.org
Context: BCO-DMO, the data repository publishing the dataset form Example 1 is an organization funded by the National Science Foundation.

{
  "@context": "http://schema.org/",
  "@id": "https://www.bco-dmo.org",
  "@type": "Organization",
  "name": "Biological and Chemical Oceanography Data Management Office",
  "alternateName": "BCO-DMO",
  "url": "https://www.bco-dmo.org",
  "funding": {
    "@type": "MonetaryGrant",
    "name": "BCO-DMO: Accelerating Scientific Discovery through Adaptive Data Management",
    "url": "https://www.nsf.gov/awardsearch/showAward?AWD_ID=1924618",
    "funder": {
      "@type": "FundingAgency",
      "name": "National Science Foundation",
      "alternateName":  "NSF",
      "sameAs": "https://doi.org/10.13039/100000001"
    }
  }
}

[ashepherd]

Just trying to keep process moving here. @stain, does #2618 (comment) address your need as well?

[horsburgh]

Hi everyone. I'm working on implementing Schema.org metadata for the HydroShare (http://www.hydroshare.org) data repository. The "funding" property described in this pull request would be really useful for us and would meet our use cases well for representing funding agency information provided by data submitters. The comment submitted above by @ashepherd describes HydroShare's use cases nicely.

[danbri]

I think we're long overdue for a community call on this (zoom, Matrix, Hangouts, whatever...). Who would be available for this, sometime early-mid April?

[ashepherd]

Thanks @danbri....I'd be happy to participate and provide use cases on consuming and publishing. @smrgeoinfo @datadavev @mbjones

[mbjones]

I'm happy to participate as well. @ashepherd Would either the April 5th (2pm pacific time) or April 22 (11:30am pacific time) science on schema.org calls be an appropriate venue for such a discussion?

[ashepherd]

@danbri, our Science-on-schema.org group from ESIP meets April 5th at 2pmPT but not sure if that's too late? In case that works, here's the Zoom info

Telecons via Zoom
https://us02web.zoom.us/j/85680809640?pwd=a09zQTl2eFd6NnpoRkRxNHlDdFN0dz09
Meeting ID: 856 8080 9640
Passcode: 002196
1st Monday at 5pmET
4th Thursday, 2:30pmET
Agenda: https://docs.google.com/document/d/1tIlDVnKeocO1E_SSbNaldv0avORfGFdmYDNk_3ub6ik/edit#heading=h.4xwgesonwtsl

[njarboe]

We use schema.org metadata for our paleomagnetic data repository MagIC (earthref.org/MagIC) and having a funding/funder type property in schema.org is important to us. Adding "funded" or "fundedBy" would be great.

[nokome]

We also need to support such a property for capturing funding details of an (executable) Article. We've added fundedBy as an array of Grant or MonetaryGrant to our extension to CreativeWork but it would be great if it was added to schema.org.

[mbjones]

@nokome and @njarboe Over at https://science-on-schema.org we've been discussing this and have a proposed approach using @reverse schema:fundedItem. Details are:

• Proposed Funding guidance to implementors: https://github.com/ESIPFed/science-on-schema.org/blob/feature_109_funding/guides/Dataset.md#funding
• DIscussion of @reverse versus a dedicated inverse property: https://github.com/ESIPFed/science-on-schema.org/blob/feature_109_funding/decisions/109-funding.md

We plan to adopt this approach and promote it across the science community until schema.org adds the needed inverse property. Feedback on our proposed approach fantastic.

Here's the example JSON-LD snippet from our guidance docs if people just want to see our representation:

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  "@id": "https://doi.org/10.18739/A22V2CB44",
  "name": "Stable water isotope data from Arctic Alaska snow pits in 2019",

  "@reverse": {
    "fundedItem": [
      {
        "@type": "MonetaryGrant",
        "@id": "https://www.nsf.gov/awardsearch/showAward?AWD_ID=1604105",
        "identifier": "1604105",
        "name": "Collaborative Research: Nutritional Landscapes of Arctic Caribou: Observations, Experiments, and Models Provide Process-Level Understanding of Forage Traits and Trajectories",
        "url": "https://www.nsf.gov/awardsearch/showAward?AWD_ID=1604105",
        "funder": {
            "@id": "http://dx.doi.org/10.13039/100000001",
            "@type": "Organization",
            "name": "National Science Foundation",
            "identifier": [
              "http://dx.doi.org/10.13039/100000001",
              "https://ror.org/021nxhr62"
            ]
        }
      },
      {
        "@type": "MonetaryGrant",
        "@id": "https://akareport.aka.fi/ibi_apps/WFServlet?IBIF_ex=x_hakkuvaus2&HAKNRO1=316349&UILANG=en&TULOSTE=HTML",
        "identifier": "316349",
        "name": "Where does water go when snow melts? New spatio-temporal resolution in stable water isotopes measurements to inform cold climate hydrological modelling",        
        "url": "https://akareport.aka.fi/ibi_apps/WFServlet?IBIF_ex=x_hakkuvaus2&HAKNRO1=316349&UILANG=en&TULOSTE=HTML",
        "funder": {
            "@id": "http://dx.doi.org/10.13039/501100002341",
            "@type": "Organization",
            "name": "Academy of Finland",
            "identifier": [
              "http://dx.doi.org/10.13039/501100002341",
              "https://ror.org/05k73zm37"
            ]
        }
      }
    ]
  }
}

[nokome]

Thanks @mbjones, that approach sounds really sensible to me. In Stencila's schema, we'll keep the fundedBy property that we currently have but in our JSON-LD "codec" we will aim to encode that as "@reverse": { "fundedItem" : stencila/encoda#934

[datadavev]

Note that the above is functionally identical to the following. Consumers should handle appropriately:

{
  "@context": "http://schema.org/",
  "@graph": [
    {
      "@type": "Dataset",
      "@id": "https://doi.org/10.18739/A22V2CB44",
      "name": "Stable water isotope data from Arctic Alaska snow pits in 2019"
    },
    {
      "@type": "MonetaryGrant",
      "@id": "https://www.nsf.gov/awardsearch/showAward?AWD_ID=1604105",
      "fundedItem": "https://doi.org/10.18739/A22V2CB44",
      "identifier": "1604105",
      "name": "Collaborative Research: Nutritional Landscapes of Arctic Caribou: Observations, Experiments, and Models Provide Process-Level Understanding of Forage Traits and Trajectories",
      "url": "https://www.nsf.gov/awardsearch/showAward?AWD_ID=1604105",
      "funder": {
        "@id": "http://dx.doi.org/10.13039/100000001",
        "@type": "Organization",
        "name": "National Science Foundation",
        "identifier": [
          "http://dx.doi.org/10.13039/100000001",
          "https://ror.org/021nxhr62"
        ]
      }
    },
    {
      "@type": "MonetaryGrant",
      "@id": "https://akareport.aka.fi/ibi_apps/WFServlet?IBIF_ex=x_hakkuvaus2&HAKNRO1=316349&UILANG=en&TULOSTE=HTML",
      "fundedItem": "https://doi.org/10.18739/A22V2CB44",
      "identifier": "316349",
      "name": "Where does water go when snow melts? New spatio-temporal resolution in stable water isotopes measurements to inform cold climate hydrological modelling",
      "url": "https://akareport.aka.fi/ibi_apps/WFServlet?IBIF_ex=x_hakkuvaus2&HAKNRO1=316349&UILANG=en&TULOSTE=HTML",
      "funder": {
        "@id": "http://dx.doi.org/10.13039/501100002341",
        "@type": "Organization",
        "name": "Academy of Finland",
        "identifier": [
          "http://dx.doi.org/10.13039/501100002341",
          "https://ror.org/05k73zm37"
        ]
      }
    }
  ]
}

[mbjones]

@datadavev Yeah, it's logically identical except that the @graph pattern puts multiple types at the top level of the graph, so I might add a schema:mainEntityOfPage pointing at the schema:Dataset entry.

[datadavev]

The node identifiers can provide such disambiguation. Providing, of course, the values correspond with representations of the respective nodes.

@datadavev Yeah, it's logically identical except that the @graph pattern puts multiple types at the top level of the graph, so I might add a schema:mainEntityOfPage pointing at the schema:Dataset entry.

[stain]

So I see the use of @reverse: fundedItem here from @mbjones as indicator that we need the inverse property – there is going to be a lot more of funded items describing their funding than funders decscribing what they funded (they need the first annotations to find out!)

[stain]

Can we bypass all the complicated questions on domain/range in #383 thread, and agree that we can't let https://schema.org/Grant stay as-is with documentation of a non-existing funding property?

To me there seems to be consensus that funding is needed from CreativeWork, Projects and beyond to avoid climbing down through the inverse fundedItem?

[danbri]

Any objections ?

…

On Thu, 20 Jan 2022 at 13:09, Stian Soiland-Reyes ***@***.***> wrote: Can we bypass all the complicated questions on domain/range in #383 <#383> thread, and agree that we can't let https://schema.org/Grant stay as-is with documentation of a non-existing funding property? To me there seems to be consensus that funding is needed from CreativeWork, Projects and beyond to avoid climbing down through the inverse fundedItem? — Reply to this email directly, view it on GitHub <#2618 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABJSGMWPFZAET3U4NDPSKTUXACQTANCNFSM4OLLL4GQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[ashepherd]

not by me!

[mbjones]

That would be welcome as a change.

[nokome]

I'm in favour. Thanks to @stain for putting this PR together and persisting with it!

[smrgeoinfo]

None! it would be a welcome addition

[danbri]

I have in effect merged this manually, so I'll close the PR. Thanks, everyone!

[mbjones]

Thanks @danbri that's fantastic.