Podspec Syntax Reference should document the JSON podspec format

[irace]

The Podspec Syntax Reference should be updated to also document the JSON format. This would make it significantly easier to build tooling on top of the JSON specifications.

For example, in Ruby there are three different ways to populate the authors field. It'd be great to document if these three different ways are also valid in JSON.

[segiddins]

The syntax reference is made by parsing the ruby documentation for the podspec DSL. Additionally, I believe the JSON we accept is stricter than the Ruby, with regards to what my be in an array, etc. @kylef do you know of any good ways of documentating JSON structure?

[kylef]

I've actually been wanting to create an issue regarding this. I was going to propose we switch documenting for podspecs away from Ruby and into Markdown (or an alternative).

Currently the documentation and specification for a podspec is tightly coupled with our own Ruby implementation. I'd like to suggest we move away from this approach and create a separate specification outside of the implementation for how a pod spec is structured completely away from the code (and the guides). The guides should then be built upon that specification.

The specification should be usable for people to build their own tools to parse JSON pod specs, for example, a pod search engine, or even integrations to clients such as AppCode. Currently there is no concrete specification, only the code documentation embedded in the Ruby DSL.

We have also had issues opened in the past of users who want to contribute to the pod spec "documentation" couldn't figure out how to, unfortunately I can't find any examples of this.

There is a specification called MSON (Markdown Syntax for Object Notation) which allows you to notate object structures right in Markdown. It uses semantics on-top of markdown to provide this, it's similar to JSON Schema. We could also use JSON Schema, however I see many downsides to JSON Schema over Markdown. Since markdown is user friendly and we can render it to HTML directly.

---

How this might look as a specification

Please note, this is really minimal. I'm just outlining a few features.

Markdown

## Podspec

A specification describes a version of Pod library. It includes details about where the source should be fetched from, what files to use, the build settings to apply, and other general metadata such as its name, version, and description.

- name (string, required) - The name of the pod
- version (SemanticVersion, required) - The version of the pod
- summary (string, required) - A short summary of the pod
- license (License, required) - The license for the pod

    This information is used by CocoaPods to generate acknowledgement
    files (markdown and plist) which can be used in the acknowledgements
    section of the final application.

- homepage (URL, optional) - The URL of the homepage of the Pod.
- source_files (FilePatterns, optional) - The source files of the Pod.
- requires_arc (enum, required)
    - (bool)
    - (FilePatterns)

## SemanticVersion (string)

A string following semantic versioning.

## License (object)

- type (string, required) - The type of license
- file (string, optional) - The path to the license
- text (string, optional) - The contents of the LICENSE

## URL (string)
A resolvable [RFC3986] URL.

---

NOTE: Full disclosure, I do work for the company that produced MSON.

• MSON Specification + more examples: https://github.com/apiaryio/mson
• MSON AST: https://github.com/apiaryio/mson-ast

/cc @alloy @orta

[neonichu]

@kylef That would also mean moving the guides away from Ruby specs as the primary form to JSON, though.

[orta]

MSON looks cool. The idea works for me in principal.

Personally, I'm in no rush to re-write large chunks of the guides and de-gut Core when there are issues with significantly more impact on the web side still to do. Others are welcome to dig in though.

Though this doesn't necessarily fix the actual problem that @irace asked for. Which is documentation specifically for the JSON format. It would be shuffling existing docs and then presumably adding it inline. As far as it goes I'm not seeing a particular demand for this outside of just @irace at the minute too.

[irace]

As far as it goes I'm not seeing a particular demand for this outside of just @irace at the minute too.

This is probably true. The lack of documentation isn't really impacting me specifically, but I think this raises a bigger question which is: are JSON podspecs intended to be on equal footing with their Ruby equivalents? They seem to be pretty clearly a second class citizen.

From my perspective, this seems less than ideal. Just about every iOS developer is familiar with JSON, while Ruby DSLs raise the barrier to entry (not by much, but at least somewhat).

Additionally, since JSON is what the Specs repo contains, it's bizarre to context-shift between writing specs in one format (ostensibly Ruby, since that's what anyone who looks at the documentation will see) and reading them in another (unless I'm the only person who actually reads through specs in the repo while researching a potential new dependency).

The blog post introducing Trunk addressed the dichotomy of spec formats as follows:

Will the specs in the Ruby format be deprecated?
No, they are here to stay and are the preferred method if you need to be able to perform automatic generation, such as collecting a list of all the source files from disk. The pod trunk push command will take care of converting the podspec to JSON. This means that you do not have to change any existing podspecs.

The preferred method if you need to be able to perform automatic generation. Since I don't, and since I've never written a line of Ruby outside of my own Podfiles or Podspecs, I was happy to switch over to using JSON for all of my specs (and even start playing around with some tooling).

But I keep running into things that make it seem as though JSON is only being supported somewhat begrudgingly.

[colinbrash]

This continues to be an issue over a year later, and it may have effects the Cocoapods dev team has not foreseen.

One of our clients has an internal podspec repo and we are spending much too much thought on whether we should allow JSON specs or not. No one truly understand what the ramifications are of one vs. the other. The only thing we have to go on right now for JSON format reference is that blog post, plus the examples in the repo.

We don't understand:

• Are there limitations to one or the other?
• Is one the preferred format?
• What is the format? (For the most part it does seem to line up with the Ruby format, but where are the differences?)
• What is the intended future of podspecs? (Support both formats indefinitely? Phase one out someday?)

As far as it goes I'm not seeing a particular demand for this outside of just @irace at the minute too.

This is a self fulfilling prophecy. If you do not document the JSON format and discuss it, demand will of course be extremely low. Even if they learn about it somehow, no one wants to adopt something that has zero public support.

[orta]

This post feels a little bit confrontational for bringing up a thread from 2014. Please be more respectful.

The CocoaPods Specs repo is, and always will be JSON. So it's always going to be supported in CocoaPods. We do that so that you don't have to have arbitrary code running on your computer.

Are there limitations to one or the other?

Ruby Podspec are turing-complete, JSON specs are not. They both can turn in the same model objects in CocoaPods though.

Is one the preferred format? What is the format? (For the most part it does seem to line up with the Ruby format, but where are the differences?)

Yes, Ruby.

What is the intended future of podspecs? (Support both formats indefinitely? Phase one out someday?)

The same as it has been, you should be making Ruby podspecs, as this thread shows, if you care enough you can make JSON podspecs but you're going against the grain. No phasing out.

[orta]

Which brings me to another point I guess, I said I wasn't planning on doing it back in 2014, I'm not definitely not going to build it into the guides in 2016, so this issue can probably be closed.

If someone makes a PR adding it all, I'm game for discussing it there, but I'm not planning on adding support.

[irace]

Agree with @orta, please keep discourse civil.

The same as it has been, you should be making Ruby podspecs, as this thread shows, if you care enough you can make JSON podspecs but you're going against the grain.

If this is the case due to lack of resources on the CocoaPods team to fully document the JSON pod spec file, audit all the places in which the CocoaPods CLI tools assume Ruby, etc., I 100% understand.

If this is an explicit design decision, I'd love more context around why.

[orta]

Nah, not an explicit design decision, Ruby offers more dev freedom and easily is transformed into the other.

[irace]

Thanks!

I’d like to think that, all things being equal, JSON would be the preferred format while Ruby would still be there for power users.

But all things aren’t equal and considering I’m not spending my own time making this so, no complaints from me 👍 👍

[orta]

hah - but yeah, I know where your coming from.

[colinbrash]

Apologies if my post sounded confrontational or uncivil. That certainly was not the intention.
And thanks for taking the time to clarify, this is helpful for our team.

[mknippen]

+1 on this thread. If it's something that the Cocoapods team has supported for 4+ years now, it would be great to have documentation for it.