Extend SwiftPM `PackageDescription` to introduce metadata

Evolution Pitches
44

As a counterpoint, package.json, the manifest file for Node.js / NPM, is used by more than 1 million packages, making it the largest package ecosystem of any programming language. While there's plenty of criticism to go around about the limitations as a hand-edited format (and some clever workarounds), the decision to use JSON hasn't been a deal-breaker for JavaScript. While sometimes "inconvenient", I wouldn't go as far as to say that it's "inappropriate".

But if the lack of comments is indeed a dealbreaker, there are alternatives like JSONC and JSON5 that improve human edibility without straying too far from the JSON-LD target.

2 Likes
45

We would do well to remember progressive disclosure as a guiding philosophy even in the case of tooling, just as it has always been for the programming language itself. Even a novice should be able to share their project with the world, with their name attached to it, with a minimum of trouble.

As the formats we use get more esoteric or its syntactic demands more stringent, we do have to be cognizant that we are pushing the limits here. I agree with earlier comments that JSON-LD may be fine as an intermediate format. But in terms of what, in my view, is clearly inconsistent with the principle of progressive disclosure, consider the following scenario:

New Swift user: I just want to put down my name as the author of this Swift package I'm really proud of in order to share it with the world.

Swift documentation: Great, create a new file in JSON-LD format using the schema.org vocabulary. Be sure to include the following so that your package is known to be written in Swift:

  "@context": ["http://schema.org/"],
  "@type": "SoftwareSourceCode",
  "identifier": "@yourname/YourProject",
  "name": "YourProject",
  ...
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "Swift",
    "url": "https://swift.org"
  },
  "author": {
      "@type": "Person",
      "@id": "https://github.com/yourname",
      "givenName": "First Name",
      "middleName": "Middle Name",
      "familyName": "Last Name"
  }

New Swift user: I...don't understand. What's JSON-LD? What's schema.org? What's a schema for that matter? Why do I have to specify that Swift is a programming language? I just want to write my name down somewhere so that users know I made this thing I'm proud of...

Just as Swift deliberately enables a complete "Hello, World!" program to be written as a one-liner without any other ceremony--

print("Hello, World!")

--(as opposed to, for example, Java's public static void main(String[] args)), it's important that we aim for a comparable amount of approachability for simple metadata. One reason that I suggested YAML as the user-facing format (which I left unsaid earlier) is that the new Swift user in the scenario above shouldn't have to contend with more than writing:

author: Me
13 Likes
46

This crystallizes my underlying belief, which is that while an RDF representation would be nice to have, it should be produced by Appropriate Tooling™ from a domain-specific, author-friendly format. I didn’t say that before because it leads to questions of who should run that tooling and where the output might be found, but I think those are matters for RDF proponents to solve.

(In particular, having five lines of JSON in your repo to specify that your SwiftPM project is in Swift is silly.)

It’s probably still valuable to consider the SoftwareSourceCode schema when considering what standard keys might be useful. However, care should be given to not mandate or encourage redundant representation of information that can be derived automatically.

For example, if the Appropriate Tooling™ is reading from a GitHub repo that has issue tracking enabled, the codeRepository, readme, license and issueTracker properties can all be inferred, and even name and description have sensible defaults.

47

I completely agree. And I think JSON-LD actually aligns closely with a notion of progressive disclosure.

The example I provided was maximal, attempting to demonstrate the full capability of the format. (In your analogy of print, I started with print(_:separator:terminator:to:). By contrast, here's a minimal example:

{
  "@type": "Package",
  "name": "LinkedList",
  "description": "One thing links to another.",
  "author": {
    "@type": "Person",
    "name": "Mona Lisa Octocat"
  }
}

Here, a @type of "Package" is effectively an an alias to / subclass of SoftwareSourceCode, with Swift as the programming language.

As you and @jayton both correctly point out, there's a lot of context that can be inferred. To that end JSON-LD has a robust mechanism for projecting that context in a formal way. From this JSON-LD Primer:

JSON-LD provides the ability to add "context" to the data and "coerce" values into forms that are easier to process. In fact, the end result of good JSON-LD usage is data structures that look like simple JSON but are in fact full linked data graphs. This provides a good deal of power for application developers to convert the linked data they are processing into easily manipulatable JSON data.

2 Likes