This documents the Request/Response API as it is currently.
For specific details related to Swift see SwiftSupport.txt

The format is
{
    <KEY>: (type) // comments
    ... 
}

"{ }" indicates dictionary
"[ ]" indicates array.
"[opt]" indicates optional key

Specific UIDs are written as <UID string>


================================================
Requests
================================================

=== Code-Completion ===

// If "SourceText" is provided, "SourceFile" is ignored. Not specifying either one is erroneous.
Request:
{
    <key.request>:          (UID) <source.request.codecomplete>
    [opt] <key.sourcetext>: (string) // source contents
    [opt] <key.sourcefile>: (string) // absolute path to the file
    <key.offset>:           (int64) // byte offset of code-completion point inside the source contents
    [opt] <key.compilerargs> [string*] // array of zero or more strings for the compiler arguments
                                       // e.g ["-sdk", "/path/to/sdk"]
    [opt] <key.not_recommended> [bool] // true if this result is to be avoided, e.g. because
                                       // the declaration is unavailable.
}

Response:
{
    <key.results>: (array) [completion-result*]  // array of zero or more completion-result dictionaries
}

completion-result ::=
{
  <key.description>:    (string) // text to be displayed in code-completion window
  <key.kind>:           (UID)    // UID for the declaration kind (function, class, etc.)
  <key.sourcetext>:     (string) // text to be inserted in source
  <key.typename>:       (string) // text describing the type of the result
  <key.doc.brief>:      (string) // brief documentation comment attached to the entity
  <key.context>:        (UID)    // semantic context of the code completion result
  <key.num_bytes_to_erase>: (int64) // number of bytes to the left of the cursor that should be erased before inserting this completion result
}

Testing:
$ sourcekitd-test -req=complete -cc-offset=<offset> <file> [-- <compiler args>]


=== Indexing ===

// If "SourceText" is provided, "SourceFile" is ignored. Not specifying either one is erroneous.
// If <key.hash> is provided and matches the hash of the indexed file then the
// <key.entities> entry will be missing from the response. 
Request:
{
    <key.request>:          (UID) <source.request.indexsource>
    [opt] <key.sourcetext>: (string) // source contents
    [opt] <key.sourcefile>: (string) // absolute path to the file
    [opt] <key.compilerargs> [string*] // array of zero or more strings for the compiler arguments
                                       // e.g ["-sdk", "/path/to/sdk"]
    [opt] <key.hash>: (string) // known hash for the indexed file
}

// If <key.hash> was provided in the indexing request and matches the hash in the response
// then the <key.entities> entry will be missing from the response. 
Response:
{
    <key.dependencies>: (array) [dependency*]  // array of zero or more dependencies
    <key.hash>:     (string) // Hash associated with the indexed file
    [opt] <key.entities>: (array) [entity*]  // array of zero or more top-level indexed entities
}

entity ::=
{
    <key.kind>:             (UID)    // UID for the declaration or reference kind (function, class, etc.)
    <key.name>:             (string) // displayed name for the entity
    <key.usr>:              (string) // USR string for the entity
    <key.line>:             (int64)  // Line of the position of the entity in source contents.
    <key.column>:           (int64)  // Column of the position of the entity in source contents.
    [opt] <key.entities>:   (array) [entity+] // one or more entities contained in the particular entity (sub-classes, references, etc.)
    [opt] <key.related>:    (array) [entity+] // one or more entities related with the particular entity (inherited classes, protocols, etc.)
}

dependency ::=
{
    <key.kind>:        (UID)    // UID for the kind (import of a swift module, etc.)
    <key.name>:        (string) // displayed name for dependency
    <key.filepath>:    (string) // path to the file
    [opt] <key.hash>:  (string) // Hash associated with this dependency
}

Testing:
$ sourcekitd-test -req=index <file> [-- <compiler args>]


=== DocInfo ===

{
  "key.request": source.request.docinfo,
  "key.modulename": "Foundation",
  "key.compilerargs": ["-sdk", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk"]
}

This will return:

key.sourcetext:
    The pretty-printed module interface in swift source code

key.annotations:
    An array of annotations for the tokens of source text, they refer to the text via offset+length entries. This includes syntactic annotations (e.g. keywords) and semantic ones. The semantic ones include the name and USR of the referenced symbol.

key.entities:
    A structure of the symbols, similar to what the indexing request returns (a class has its methods as sub-entities, etc.). This includes the function parameters and their types as entities.
    Each entity refers to the range of the original text via offset+length entries.


For source text (you can also pass a source filename with "key.sourcefile")

{
  "key.request": source.request.docinfo,
  "key.sourcefile": "/whatever/virtual/path",
  "key.sourcetext": "import Foundation\n var s: NSString\n",
  "key.compilerargs": ["/whatever/virtual/path", "-sdk", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk"]
}

This will return

key.annotations
key.entities
    which will refer to the original text.

and

key.diagnostics
    for any compiler diagnostics during parsing

=== Module interface generation ===

Request:
{
    <key.request>:          (UID) <source.request.editor.open.interface>
    <key.name>:             (string) // virtual name/path to associate with the interface document
    <key.modulename>:       (string) // Full module name, e.g. "Foundation.NSArray"
    [opt] <key.compilerargs> [string*] // array of zero or more strings for the compiler arguments
                                       // e.g ["-sdk", "/path/to/sdk"]
}

This will return the Swift interface of the specified module.

key.sourcetext:
    The pretty-printed module interface in swift source code

key.syntaxmap:
    An array of syntactic annotations, same as the one returned for the source.request.editor.open request.

key.annotations:
    An array of semantic annotations, same as the one returned for the source.request.editor.open request.


All SourceKit requests that don't modify the source buffer should work on the
opened document, by passing the associated 'name' for the document.

If pointing at a symbol which came from a clang module or the stdlib, then the
response for the cursor-info request will have an entry for the module name:

  key.modulename: "<module-name>"

Also if there is already a generated-interface document for this module
previously opened, there will be an entry with the "virtual name" associated
with this document (from the previous 'editor.open.interface' request):

  key.module_interface_name: "<virtual name for interface document>"


After 'opening' the module interface, to 'jump' to the location of a declaration
with a particular USR, use the 'find_usr' request:

Request:
{
    <key.request>:       (UID) <source.request.editor.find_usr>
    <key.usr>:           (string) // USR to look for.
    <key.sourcefile>:    (string) // virtual name/path associated with the interface document
}

This returns the byte offset if the USR is found, or an empty response otherwise:

  key.offset: <byte offset in the interface source>


================================================
Diagnostics
================================================

Diagnostic entries occur as part of the responses for editor requests.
If there is a diagnostic, <key.diagnostics> is present and contains an array
of diagnostic entries. A diagnostic entry has this format:

{
    <key.severity>:         (UID)   // severity of error
    <key.offset>:           (int64) // error location
    <key.description>:      (string) // error description
    [opts] <key.fixits>:    (array) [fixit+] // one or more entries for fixits
    [opts] <key.ranges>:    (array) [range+] // one or more entries for ranges
    [opts] <key.diagnostics>: (array) [diagnostic+] // one or more sub-diagnostic entries
}

severity can be one of:
  source.diagnostic.severity.note
  source.diagnostic.severity.warning
  source.diagnostic.severity.error

fixit ::=
{
    <key.offset>:        (int64) // location of the fixit range
    <key.length>:        (int64) // length of the fixit range
    <key.sourcetext>:    (string) // text to replace the range with
}

range ::=
{
    <key.offset>:        (int64) // location of the range
    <key.length>:        (int64) // length of the range
}

sub-diagnostics are only diagnostic notes currently.

================================================
UIDs
================================================

=== Keys ===

key.column
key.compilerargs
key.description
key.kind
key.line
key.name
key.offset
key.results
key.request
key.sourcefile
key.sourcetext
key.typename
key.usr